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
:
unscrambl.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.unscrambl.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 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 thefirewalld
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