Configuring and Running Unscrambl Drive

Configuring a web proxy

Unscrambl Drive consists of a set of backend services, accessible via a web-based user interface.

Once installed, an instance of Unscrambl Drive can be started. The communication between the web-based user interface and the backend employs REST APIs over HTTP or HTTPS.

Unscrambl strongly recommends that HTTPS be used to ensure that the sensitive information that transits over the network is encrypted.

As seen in the Installation Process section, Unscrambl Drive offers the choice of web transport protocols during its installation process and recommends HTTPS with the use of a web proxy as the means to access its private backend services.

This option requires installing Unscrambl Drive with HTTP support, where the backend is bound only to the local lo network interface, allowing HTTP access only within the host where the Unscrambl Drive web server runs.

Either of two commonly used web proxies, packaged an available in the Linux distributions supported by Unscrambl Drive, can be configured to provide the HTTPS-based access to the users interacting with Unscrambl Drive via their web browsers: Apache httpd and nginx.

In either case, two steps must be carried out prior to the web proxy installation and configuration. These steps and the specific configuration of a web proxy are outlined next.

Configuring a DNS CNAME entry to point to Unscrambl Drive (optional)

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

Usually, the friendlier unscrambl name will map to an internal server hosting the Unscrambl Drive 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 Unscrambl Drive installation.

Procedures to update the corporate DNS servers vary. We recommend that the system administrator installing Drive 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:

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

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

Obtaining an SSL certificate

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 Unscrambl Drive, 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 unscrambl.acme.com:

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 7 (or CentOS 7) server, where the Unscrambl Drive web backend will eventually run.

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

Configuring Apache httpd

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 unscrambl.acme.com
    ## Unscrambl Drive will accessible at https://unscrambl.acme.com/drive
    ProxyPass /drive http://[::1]:8081/drive
    ## Unscrambl Drive 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.
    ## Unscrambl Drive's Tomcat instance by ## default will use the IPv6 protocol stack
    ProxyPassReverse /drive http://[::1]:8081/drive
    ProxyPreserveHost on
    ProxyRequests off
    SSLCertificateFile /etc/httpd/stash/unscrambl.acme.com/fullchain.pem
    SSLCertificateKeyFile /etc/httpd/stash/unscrambl.acme.com/privkey.pem
    SSLEngine on
    SSLProxyEngine on
</VirtualHost>
...

Note that in our configuration we chose to install the certificate-related files under /etc/httpd/stash. This is not necessary, but is convenient as far as applying the correct SE Linux context to these files, which is carried out as follows:

$ restorecon -vr /etc/httpd/stash

Once this is done, httpd can be started (or restarted):

$ systemctl start httpd

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

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

Configuring nginx

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 unscrambl.acme.com;

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

        ssl_session_cache shared:SSL:10m;
        ## Unscrambl Drive will accessible at https://unscrambl.acme.com/drive
        location /drive {

            ## Unscrambl Drive 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. Unscrambl Drive'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;
        }
    }
}

Note that in our configuration we chose to install the certificate-related files under /etc/httpd/stash. This is not necessary, but is convenient as far as applying the correct SE Linux context to these files, which is carried out as follows:

$ restorecon -vr /etc/nginx/stash

Once this is done, nginx can be started (or restarted):

$ systemctl start nginx

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

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

Starting and stopping Unscrambl Drive

Starting Unscrambl Drive requires two steps.

First, we must ensure that the environment in the current shell is properly configured. This is accomplished by sourcing the script that performs this task:

$ source <installation-location>/drive/bin/environment_setter

Next, we start all of the Unscrambl Drive services:

$ <installation-location>/drive/bin/services_manager start

At this point, it is possible to open a browser on any computer with access to the server where Unscrambl Drive is installed and access its web user interface by pointing the browser to the appropriate URL: https://unscrambl.acme.com/drive`.

If everything has worked correctly, you will be presented with the initial setup workflow, whereby an administration password will be configured as well as other initialization steps.

If you cannot access the Unscrambl Drive UI, the Testing and troubleshooting the web proxy installation section provides a few troubleshooting instructions that will help you ensure that your configuration is correct.

Finally, we can stop the Unscrambl Drive services:

$ <installation-location>/drive/bin/services_manager stop

Testing and troubleshooting the web proxy installation

Once the web proxy is configured and Unscrambl Drive 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. Unscrambl 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