Product installation

Summary

This section provides instructions for an on-premise deployment of Unscrambl qbo insights.

The following sections assume that you have access to an appropriately sized x86 based RHEL or CentOS machine (virtual or otherwise). Unscrambl qbo insights supports RHEL or CentOS 7.2.0 or higher.

Prerequisites

Before installing the qbo insights software, setting up an internal database as well as installing external dependencies are the indispensable prerequisites. We will see them in detail as mentioned below.

Setting-up internal database

About MariaDB

qbo insights requires a relational database to store configuration as well as runtime data as it runs.

Currently, the only database supported for storage of qbo insights’ internal configuration is MariaDB.

Installing MariaDB

To install and configure MariaDB prior to the installation qbo insights, please refer to the MariaDB’s online installation instructions. The actual installation is done via apt-get or yum, depending on whether it is getting installed on Ubuntu or RedHat.

MariaDB is executed as a service on both Ubuntu as well as on RedHat and its behavior is controlled by a configuration file (usually located in /etc/my.cnf.d/server.cnf or /etc/mysql/my.cnf). In this file, specifically in the mysqld section of the configuration, the following entry must be commented out or removed:

bind-address = 127.0.0.1

This change will ensure that other hosts in the cluster can interact with the MariaDB server.

If the version of your MariaDB server is older than 10.3.1, the InnoDB engine must also be appropriately configured with the following settings in the file /etc/my.cnf.d/server.cnf under [mysqld] section of the root user.

innodb_file_format=Barracuda

innodb_file_per_table=ON

innodb_large_prefix=ON

Configuration modifications become active only after a server restart, which requires restarting the specific operating system service as follows.

On RedHat:

$ sudo service mariadb restart

On Ubuntu

$ sudo service mysql restart

Finally, ensure that the MariaDB server is automatically started at the boot time by appropriately configuring init, systemd, cron, or any other mechanism that is in place for automating the startup of services.

Securing MariaDB

Once the installation is performed, it is also recommended that MariaDB’s installation and configuration be secured:

$ sudo mysql_secure_installation

The simplest way to make the MariaDB server (mysqld) available to qbo insights is to install it on the same host where qbo insights is going to be installed. It is also necessary to ensure that the server is using its default port (3306):

$ netstat -lptn | grep 3306

This will give output:

tcp   0   0 0.0.0.0:3306   0.0.0.0:*   LISTEN   11430/mysqld

Note that placing the MariaDB server on another host as well as using a different port number can be done, but both of these options require an additional configuration (outlined in Using a non-default MariaDB configuration).

Populating the MariaDB Timezone Tables

Several tables in the MariaDB system database exist to store the time zone information.

The MariaDB installation procedure creates the time zone tables, but does not load them. To load them manually, as root run the following command. MariaDB’s root password will be requested.

$ mysql_tzinfo_to_sql /usr/share/zoneinfo | mysql -u root -p mysql

There will be one or two warnings as mentioned below. These warnings can be ignored.

This will give output:

Warning: Unable to load `/usr/share/zoneinfo/leap-seconds.list` as time zone. Skipping it.

Loading the time zone information is not necessarily a one-time operation because the information changes occasionally.

When such changes occur, applications that use the old rules become out of date and you may find it necessary to reload the time zone tables (using the instructions above) to keep the information used by the MariaDB server current. Please refer to the MariaDB documentation for more information.

Setting up a MariaDB User

Once the MariaDB is properly installed, it must be configured with a user and a password. This user is used by qbo insights when establishing connections with the database server. By default, both the user and password are set to chai.

To create a MariaDB user called chai with the password chai, start MariaDB’s interactive shell using MariaDB’s root user:

$ mysql -u root -p

Then, issue the following command:

MariaDB [(none)]> CREATE USER '<user>'@'%' IDENTIFIED BY '<password>';

Now, to replace <user> and <password>, with chai specifically

MariaDB [(none)]> CREATE USER 'chai'@'%' IDENTIFIED BY 'chai';

Once the user is created, it must be given privileges to create the qbo insights databases:

MariaDB [(none)]> GRANT ALL PRIVILEGES ON  `chai_%` . * TO 'chai'@'%';

MariaDB [(none)]> FLUSH PRIVILEGES;

You can now close the MariaDB interactive shell by pressing CTRL-D (the Control and the D key, together) or by using the exit command.

At this point you should be able to login to the MariaDB using the user chai and authenticate using the initial default password you just configured:

$ mysql -u chai -p

If the new user has been properly configured, you will once again be greeted by the MariaDB interactive shell:

$ mysql -u chai -p

Enter password:

You will see:

Welcome to the MariaDB monitor. Commands end with ; or \g.

Your MariaDB connection id is 39
...

MariaDB [(none)]>

Using a Non-default MariaDB Configuration

The use of MariaDB on a different host as well as the use of a different user name and/or password requires updating the qbo insights configuration file unscrambl/etc/chai.json.

This JSON file can be edited using a regular text editor.

To change the password used by the qbo insights database server user, it is necessary to first encrypt the new password so it is not stored in clear text in the configuration file. qbo insights includes a tool that can be used to perform this operation:

$ UNSCRAMBL_HOME/bin/password_encryptor -p <new_password>

Once you have the newly encrypted password, modify the databaseConfiguration|{userName,userPassword} entry in the configuration file with the new password as well as a new user name.

The configuration file is nested, so the notation used in the prior sentence means, e.g., the entry userName as well as the entry userPassword are under the entry databaseConfiguration.

If you are changing these settings, MariaDB itself must be updated with this new user/password information.

To change the host and port, the MariaDB server uses create or update the following entry: databaseConfiguration|address. The address is a tuple with the following format: hostname:port, e.g., foo.unscrambl.com:3306.

External dependencies

The external software dependencies required by qbo insights are specific to the operating system version and the architecture where the software will run. The installer will check for and warn you about missing dependencies.

The installation package comes with a utility, dependency_checker, that can be used to ensure that all the dependencies are in place prior to the installation.

This utility inspects the environment for RedHat or Ubuntu-provided software (referred to as OS-provided software in the rest of this documentation). It also checks for specific Python packages and Node.js npm packages required by qbo insights, which are provided as a virtualenv environment (for Python) and a node modules directory (for Node.js), pre-packaged and configured to match the needs of qbo insights.

Operating System-software packages must be installed using the regular mechanism employed to download and install them, usually yum on RedHat and apt-get on Ubuntu.

When using the dependency_checker to extract the list of required dependencies, the output will be similar to the following:

$ $UNSCRAMBL_HOME/bin/dependency_checker -l

This will give output:

List of OS package dependencies:

mariadb: 5.5 (not installed)
mariadb-libs: 5.5 (installed)
mariadb-server: 5.5 (installed)

List of Python package dependencies (available in the qbo insights virtualenv):

In this example, one external dependency (mariadb) is not currently installed. In this case, assuming this host is running RedHat Linux, yum must be used to install mariadb.

Note

  • Installing OS packages on a server without Internet connection

  • Often, the server (or cluster) where qbo insights is to be installed does not have direct Internet connection.

  • In such cases, the installation of additional OS-level packages can be accomplished by having access to the Operating System installation CD/DVD or, simply, to an .iso image with the OS installation.

  • If your installation is RedHat-based, use one of the following alternatives:

  • If your installation is Ubuntu-based, use one of the following alternatives:

    • if a DVD is available, please follow the DVD-based apt repository directions outlined by Canonical to create a locally available aptitude repository.

    • if an .iso file is available, mount it first and then use the mounting point in the steps above as the location when running apt-cdrom. To mount the .iso perform the following steps either sudo-ed or by logging in as root:

  • $ mkdir -p <mounting point location>
$ mount -o loop <file>.iso <mounting point> location

  • When installing external operating system-managed dependencies, as long as the major and minor version numbers match, the dependency is considered satisfied.

Installation process

The installation process of qbo insights software involves detailed steps that needs to be thoroughly followed to have a successful installation. Let’s take a close look at each step mentioned below.

Extracting the tarball

The installation process must be carried out using the userid that will manage the qbo insights software.

It is recommended that this user be named chai.

Prior to the actual installation, if HTTPS-secured web access to qbo insights is made available, a (optional) DNS entry must be configured to provide a user-friendly URL to the end users. Also, a commercial SSL certificate must be on-hand as it will be required to complete the product installation.

It might be helpful to become familiar with the infrastructure used to provide HTTPS access to qbo by reading the steps outlined in the Configuring web proxy section before attempting the installation steps.

The installation process begins by un-tarring the software tarball. The qbo insights installation tarball includes:

  • The qbo insights software platform itself, comprising all the necessary components to run qbo insights-supported solutions.

  • The pre-configured Python virtualenv environment, comprising all Python dependencies required by qbo insights solutions to run.

  • The pre-configured npm node modules directory, comprising all Node.js dependencies required by qbo insights solutions to run.

  • The external open source software required by qbo insights, e.g., Node.js, Oracle JVM.

To extract the tarball, run the following command:

$ tar xvfz chai-1.0.0-rhel07.tar.gz

Let us assume that the tarball was extracted at a directory called $UNSCRAMBL_HOME.

The suffixes 1.0.0 denote the version you are installing and rhel07 the specific operating system (rhel7 for RedHat 7).

After extracting the tarball, the next step is to extract the software using the command:

$ mkdir -p /opt/unscrambl/chai/rhel07

$ tar xzvf chai-1.0.0-rhel07.tar.gz -C /opt/unscrambl/chai/rhel07

Again, other locations are acceptable, but /opt/unscrambl/chai/rhel07 is the recommended path.

Running the installer

Now, you are ready to perform the configuration steps:

$ cd $UNSCRAMBL_HOME/unscrambl/bin

$ ./installer

installer is an interactive program and will guide you through specific installation and configuration choices:

Unscrambl chAI is a commercial product, subjected to End-User License Agreement terms.A paper-based or digital
copy of these terms must have been signed and agreed by someone authorized to do so in your organization,
prior to carrying out this configuration. A non-customer specific copy of these terms is included for your
reference in this installation package (unscrambl/license/eula.pdf).
Do you confirm that you are authorized to proceed with the configuration based on the terms specified in your
organization's own license agreement with Unscrambl Inc. (y/n)?

As a first configuration step, you will be asked about the directory that will be used to host the qbo insights instance, i.e., the location in the file system that qbo insights will use to host its services, logs, as well as the data that will be kept by the qbo insights data management services.

Next, you will be asked which network interface to use for external TCP/IP traffic. You should choose the interface that provides connectivity to other hosts in the cluster (if any) and/or external services the qbo insights application will interface with:

Please select the network interface to use for external TCP/IP traffic (default: 'eth0'):

[0] lo: 127.0.0.1
[1] eth0 10.0.0.123.. parsed-literal::

[2] tun0: 10.8.0.45

Select the number corresponding to the interface you want (default: 1 for interface 'eth0'): 1

The 'eth0' network interface will be used for all external TCP/IP traffic.

Once a network interface is selected, the installer will proceed to ask which port should be used by qbo insights’s HTTP-based backend services:

Please enter the HTTP port for the REST server to be used by Unscrambl chAI (if left empty, the HTTP port will
be 8081):

Next, you will be asked whether qbo’s HTTP-based backend services should bind only to localhost, making qbo’s web-based front-end available behind a proxy (recommended):

When using HTTP, do you want to bind only to localhost ([y]es: only a local connection to the REST server will be
possible. This configuration is meant to be used behind a web proxy such as nginx or Apache httpd; / [n]o: remote
HTTP will be possible. This configuration is insecure and STRONGLY discouraged as all interactions between chAI's
client and its backend, including authentication, will go in the clear over network connections) (if left empty,
only a local connection to the REST server will be possible) (y/n)?

Warning

  • qbo insights has access to and handles potentially sensitive information:

  • Authentication information: in certain configurations, the use of qbo insights requires a user account. qbo insights can be configured to communicate with external services for authentication purposes, such as OpenID/OAuth providers. Such communication can carry credentials employed to ensure that a user is both authenticated and authorized to use the system. While qbo insights never stores user passwords in the clear, certain interactions require the transferring of sensitive information between the front end, web-based interface to the backend. Hence, encryption (through the use of HTTPS) is STRONGLY recommended.

  • Metadata and personal information about users and corporate data: qbo insights carries out analytics employing data that is often private and sensitive, including conversation data and data that may be accessed from corporate data sources. Once, again, interactions between its web-based interface and its backend require manipulating such data and encryption, in the form of HTTPS interactions, is STRONGLY recommended to preserve end-to-end confidentiality.

  • While in certain configurations qbo insights may be hosted in an internal network, never facing non-corporate users, it does integrate with other segments of he enterprise computing environment. Unscrambl recommends that administrators take every possible precaution to protect the integrity and confidentiality of the data consumed and produced by this platform.

There are two possible configurations to choose from:

  • HTTP, available network-wide (STRONGLY DISCOURAGED): this is the simplest form of installing qbo insights. Nevertheless, it is insecure as potentially sensitive information is transmitted in the clear, flowing from the user’s browser to the server without any encryption (potentially including passwords and credentials used for authenticating via external services such as enterprise OpenID/OAuth providers, if such an integration is enabled).

  • HTTP, available only in the localhost interface, proxied by an HTTPS web proxy (STRONGLY RECOMMENDED): this configuration is secure, as it minimizes the chances of a sensitive data breach. The interactions between the browser-based user interface and the web proxy in front of qbo insights’s backend is HTTPS encrypted. The web proxy (both Apache httpd and nginx are supported) employs a regular local HTTP connection to the qbo insights backend.

The benefit of this approach is that the web proxy (which is specifically hardened for this task), not qbo insights’s backend, runs as root and the web proxy’s internal design is optimized for these types of interactions.

In this configuration, the installation of an SSL certificate as well as the configuration of the HTTPS endpoint is done by installing and configuring the web proxy, a step described in the Configuring web proxy section.

Note

  • SSL certificates

  • An SSL certificates is a data file that digitally binds a cryptographic key to an organization’s identity. For instance, when installed on a web server, it activates the padlock used by the browser to indicate a secure connection and, hence, the HTTPS protocol in interactions between the browser and a server.

  • In general, an SSL certificate is obtained from a Certificate Authority (CA) and it attests the ownership of a public key by the named subject of the certificate, providing an assurance that an interaction is occurring between a client and a properly identified server. A CA acts as a third party, trusted both by the subject (owner) of the certificate and by the party relying upon the certificate.

  • The qbo insights web service can make use of an SSL certificate to ensure that interactions between the web-based client and server are properly authenticated (i.e., to provide an assurance to the browser-based client that it is indeed speaking to an actual server) as well as encrypted, such that no sensitive information flows over between a client and server in clear text form.

  • SSL certificates can be purchased from several vendors or obtained for free from organizations such as Let’s Encrypt.

  • Commercial SSL certificates are typically verified and accepted by mainstream web browsers such as Google Chrome and Mozilla Firefox.

  • SSL certificates can also be provided by any entity hosting a Public Key Infrastructure (PKI). For instance, an organization’s IT department might host its own internal PKI and issue self-signed certificates. These certificates work just like commercial certificates, but they will typically produce a warning or an outright rejection from web browsers, which will not recognized the PKI’s CA. In such cases, upon being directed by the organization’s IT department, the certificate may be added to the browser and accepted as legitimate, thus quieting down the warnings that would, otherwise, be raised every time a web server presenting it is accessed.

  • qbo insights can be configured with either type of certificate, but Unscrambl strongly recommends that a certificate be obtained from an officially recognized commercial or non-profit CA.

If everything is correctly configured, a success status message will be printed out:

the Unscrambl chAI environment has been configured successfully...

Configuring web proxy

qbo insights consists of a set of backend services, accessible via a web-based user interface and optionally via third-party messaging platforms.

Once installed, an instance of qbo insights can be started. The communication between the web-based user interface and the backend employs REST APIs over HTTP or HTTP via an HTTPS proxy. Accessing qbo via messaging-based channels (if configured) always requires the use of HTTP via an HTTPS proxy.

Unscrambl strongly recommends that HTTP via an HTTPS proxy be used in all cases to ensure that the sensitive information that transits over the network is encrypted.

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

Either of two commonly used web proxies, packaged and available in the Linux distributions supported by qbo insights, can be configured to provide the HTTPS-based access to the users interacting with qbo insights:

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 qbo insights (Optional)

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

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

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

virtual host entry
    <VirtualHost *:443>
        ## Unscrambl chAI will be accessible at https://unscrambl.acme.com/chai
        ServerName unscrambl.acme.com

        ## Unscrambl chAI 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 chAI's server instance will use the IPv6 protocol stack by default
        ProxyPass /chai http://[::1]:8081/chai
        ProxyPassReverse /chai http://[::1]:8081/chai

        ## Unscram    Please select the network interface to use for external TCP/IP traffic (default: 'eth0'):

        [0] lo: 127.0.0.1
        [1] eth0 1    Please select the network interface to use for external TCP/IP traffic (default: 'eth0'):

        [0] lo: 127.0.0.1
        [1] eth0 1    Please select the network interface to use for external TCP/IP traffic (default: 'eth0'):

        [0] lo: 127.0.0.1
        [1] eth0 10.0.0.123
        [2] tun0: 10.8.0.45

        Select the number corresponding to the interface you want (default: 1 for interface 'eth0'): 1

        The 'e0.0.0.123
        [2] tun0: 10.8.0.45

        Select the number corresponding to the interface you want (default: 1 for interface 'eth0'): 1

        The 'e0.0.0.123
        [2] tun0: 10.8.0.45

        Select the number corresponding to the interface you want (default: 1 for interface 'eth0'): 1

        The 'ebl chAI's web interface requires a WebSocket endpoint called 'directLine'
        to be exposed
        RewriteEngine on
        RewriteCond %{HTTP:Upgrade} websocket
        ## The port used for the 'directLine' WebSocket endpoint (8081 in this example) must
        match the port
        ## specified for the 'chai' endpoint above
        RewriteRule ^/(.*)$ ws://[::1]:8081/$1 [P]
        ProxyPass /directLine http://[::1]:8081/directLine
        ProxyPassReverse /directLine http://[::1]:8081/directLine

        ProxyPreserveHost on
        ProxyRequests off
        Header always set Strict-Transport-Security "max-age=31536000; includeSubdomains; preload"
        SSLCertificateFile /etc/httpd/stash/unscrambl.acme.com/fullchain.pem
        SSLCertificateKeyFile /etc/httpd/stash/unscrambl.acme.com/privkey.pem
        SSLEngine on
        SSLProtocol TLSv1.2
        SSLProxyEngine on
        <Location "/directLine">
            ProxyPass "ws://[::1]:8081/directLine"
        </Location>$ restorecon -vr /etc/httpd/stash</div>
    </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 qbo insights, open a browser and point it to https://unscrambl.acme.com/chai.

To start qbo insights, see the Managing qbo insights Services section.

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:

new server entry
http {
...
    server {

        listen 443;
        server_name unscrambl.acme.com;

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

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

        ## Unscrambl chAI will be accessible at https://unscrambl.acme.com/chai
        location /chai {
            ## Unscrambl chAI 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 chAI's server instance will use the IPv6 protocol
            stack by default
            proxy_pass http://[::1]:8081/chai;
            proxy_redirect off;
            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
            proxy_set_header X-Forwarded-Host $host;
            proxy_set_header X-Forwarded-Proto "https";
            proxy_set_header X-Forwarded-Server $host;
            proxy_set_header X-Real-IP $remote_addr;
        }

        ## Unscrambl chAI's web interface requires a WebSocket endpoint called 'directLine'
        to be exposed location /directLine {
            ## The port used for the 'directLine' WebSocket endpoint (8081 in this example)
            must match the port
            ## specified for the 'chai' endpoint above
            proxy_pass http://[::1]:8081/directLine;
            proxy_read_timeout 86400;
            proxy_redirect off;
            proxy_set_header Connection "upgrade";
            proxy_set_header Host $host;
            proxy_set_header Upgrade $http_upgrade;
            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
            proxy_set_header X-Forwarded-Host $host;
            proxy_set_header X-Forwarded-Proto "https";
            proxy_set_header X-Forwarded-Server $host;
            proxy_set_header X-Real-IP $remote_addr;
        }
    }
}

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 qbo insights, open a browser, and point it to https://unscrambl.acme.com/chai troubleshooting.

To start qbo insights, see the To start qbo insights, see the Managing qbo insights Services section.

Testing and Troubleshooting the Web Proxy Installation

Once the web proxy is configured and qbo insights 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 RHEL or CentOS is being used:

  • 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

This will give output:

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 that 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

This will give output:

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
possible fixes
    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 Boolean 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</soan>

$ semodule -i nginx.pp

$ rm nginx.pp

The following sections detail the process starting/stopping the product, performing one-time setup and configuring various other aspects of the product including the data source and the data model.