Single machine installation🔗

On-Premises server requirements🔗

Supported operating systems:

• Ubuntu 18.04 “Bionic Beaver”
• Red Hat Enterprise Linux 8
• CentOS 8
• Debian 9 “Stretch”

Hardware requirements:

• RAM: 2 GiB (8 GiB is recommended)
• Storage: depends on the size of the database. At least 100 GiB is recommended.

For a virtual machine, it is required to assign it at least 2 vCPUs, and recommended to assign at least 4 vCPUs.

Installing or upgrading the package🔗

Ubuntu 18.04 / Debian 9🔗

This installs the .deb file:

# dpkg -i cryptosense-analyzer_1.2.3-4_amd64.deb
# apt-get -f install

The first command may fail because of missing external dependencies. That’s expected and is fixed by the second command.

Note that in order to run AQtive Guard, the system locale must be set to use UTF-8 character encoding. This can be done by modifying the dpkg-reconfigure locales command For more information, refer to the Debian documentation.

Red Hat Enterprise Linux 8 / CentOS 8🔗

This installs the .rpm file and dependencies it can’t fetch from default repositories:

# yum install --nogpgcheck packages/*.rpm

Note that in order to run AQtive Guard, the system locale must be set to use UTF-8 character encoding. This can be done by modifying /etc/locale.conf. For more information, refer to the Red Hat documentation.

Configuring the license🔗

The Analyzer processes won’t start without a license. It should have been provided by AQtive Guard and should be put in the configuration directory:

# mv analyzer.cs-license /etc/cryptosense-analyzer/analyzer.cs-license

Make sure the file is owned by the cryptosense-analyzer user with the following command:

# chown cryptosense-analyzer:cryptosense-analyzer \
/etc/cryptosense-analyzer/analyzer.cs-license

You can check it is correctly installed with the following command:

# cs license check
License OK

Organization administration🔗

The Analyzer web process requires an organization to be created in order for users to be added. It is recommended to create a single organization for your deployment at setup-time, but organizations can be edited at any time.

Adding an organization🔗

To add an organization, the following command can be used:

# cs organization add "<name>"

In the command above, <name> is the name of the organization that you want to create. Note that only one organization can be added using this method.

At this point, you can start the processes with the following command:

# cs restart

User administration🔗

Adding a user🔗

The command for adding a user has the following syntax:

# cs user add <username>
Username: <username>
Password: secret

By default, the created user will be an administrator for your organization. The user will have access to the user management dashboard in the web interface, where additional users can be created and managed.

Resetting the password of a user🔗

# cs user reset-password <username>
New password: secret

Setting up a web server🔗

The Analyzer web process listens on localhost:8000 and isn’t exposed to the rest of the network. To do this, it is recommended to use a web server such as Apache or Nginx as a reverse proxy. Among other security advantages, this enables the use of HTTPS.

Example with Nginx on Ubuntu / Debian🔗

Install Nginx:

# apt-get install nginx

Disable the default home page:

# rm /etc/nginx/sites-enabled/default

Copy the provided configuration to the configuration directory of Nginx:

# cp cryptosense-analyzer.conf /etc/nginx/sites-available/

For information, the provided file has the following content:

    server {
        # Use HTTPS.
        listen 443 ssl;
        listen [::]:443 ssl;

        # Use default certificates.  You can customize this to use your own.
        ssl_certificate /etc/ssl/certs/ssl-cert-snakeoil.pem;
        ssl_certificate_key /etc/ssl/private/ssl-cert-snakeoil.key;

        # Allow the upload of large files (e.g. traces).
        client_max_body_size 2G;

        # Forward all requests to the local AQtive Guard application server.
        location / {
            proxy_pass http://127.0.0.1:8000;
            proxy_set_header Host $http_host;
            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
            proxy_set_header X-Forwarded-Proto https;
            proxy_connect_timeout 1200s;
            proxy_read_timeout 1200s;
        }

        location /storage-traces {
            proxy_pass http://127.0.0.1:9000;
            proxy_set_header Host $http_host;
            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
            proxy_set_header X-Forwarded-Proto https;
            proxy_connect_timeout 1200s;
            proxy_read_timeout 1200s;
        }
    }

Enable the new configuration:

# ln -s /etc/nginx/sites-available/cryptosense-analyzer.conf \
/etc/nginx/sites-enabled/cryptosense-analyzer.conf

Restart Nginx to take the new settings into account:

# systemctl restart nginx

Visit https://[YOUR_HOST_ADDRESS]/ to ensure the server works. Make sure you use https, not http.

Example with Apache HTTP Server on RHEL / CentOS🔗

Install Apache HTTP:

# yum install httpd mod_ssl

# sed --in-place 's/^/#/' /etc/httpd/conf.d/welcome.conf

Copy the provided configuration to the configuration directory of Apache HTTP:

# cp cryptosense-analyzer.conf /etc/httpd/conf.d/

For information, the provided file has the following content:

    <VirtualHost *:443>
        # Use HTTPS.
        SSLEngine on

        # Use default certificates.  You can customize this to use your own.
        SSLCertificateFile /etc/pki/tls/certs/localhost.crt
        SSLCertificateKeyFile /etc/pki/tls/private/localhost.key

        # Forward all requests to the local AQtive Guard application server.
        ProxyPass /storage-traces http://127.0.0.1:9000/storage-traces/ connectiontimeout=1200 timeout=1200
        ProxyPass / http://127.0.0.1:8000/ connectiontimeout=1200 timeout=1200
        ProxyPreserveHost on
        RequestHeader set X-Forwarded-Proto https
    </VirtualHost>

Allow Apache HTTP to connect to the internal application server:

 # setsebool -P httpd_can_network_connect 1

Restart Apache HTTP to take the new settings into account:

# systemctl restart httpd

Visit https://[YOUR_HOST_ADDRESS]/ to ensure the server works. Make sure you use https, not http.

Troubleshooting🔗

If the server does not appear to be working after following the installation instructions, then this section contains some suggestions for narrowing down the problem, and some information about which diagnostics to send to AQtive Guard to help us diagnose any problems.

Initial Debugging Steps🔗

• Check that the license has been installed correctly using the cs license check command
• Restart everything using the cs restart command
• Run the cs debug check command to diagnose issues with subcomponents of AQtive Guard
• Check whether AQtive Guard services are running correctly using systemctl status "cryptosense-*"

Debugging Command🔗

The cs command line comes with an integrated debugging tool, that allows narrowing down the source of problems with on-premise installations.

Run it using cs debug check to get a complete check of all the subcomponents of AQtive Guard, with a detailed error if a problem is detected. The tool will also suggest solutions to certain classes of problems.

Debugging Information🔗

When reporting issues to us, it is helpful to include the following debugging information:

• The output of cs license check
• The output of systemctl status "cryptosense-*"
• The output of cs debug check --verbose

Logging🔗

To access the logs generated by the AQtive Guard server, use journalctl -u <process>. The list of processes running on a server depend on the type of AQtive Guard server.

On a regular AQtive Guard server, the processes are:

• cryptosense-analyzer-frontend
• cryptosense-analyzer-worker
• cryptosense-analyzer-worker-analyzer
• cryptosense-analyzer-secret
• cryptosense-analyzer-license
• cryptosense-analyzer-database
• cryptosense-analyzer-object-storage
• cryptosense-analyzer-redis

Within a HA install of AQtive Guard, the web servers only have the following services:

• cryptosense-analyzer-frontend

Within a HA install of AQtive Guard, the worker servers only have the following services:

• cryptosense-analyzer-worker
• cryptosense-analyzer-worker-analyzer

If logging to a file is required, refer to the Logging section of the Configuration Guide.

Running cs commands without sudo🔗

In order to run cs commands without sudo:

• Add a shell to the cryptosense-analyzer user: usermod --shell "<path to your shell>" "cryptosense-analyzer"
• Add a password to the cryptosense-analyzer user: passwd "cryptosense-analyzer"
• Add the cryptosense-analyzer user to the systemd-journal group: usermod -a -G systemd-journal "cryptosense-analyzer". The exact group name might be different in different environments.
• And finally, add the polkit rule to allow the cs application to be restarted.

Polkit rule to let users restart the server🔗

To allow users to restart the server, the following polkit rule can be used:

polkit.addRule(function(action, subject) {
    if (action.id == "org.freedesktop.systemd1.manage-units" &&
        action.lookup("unit") == "cryptosense-analyzer-frontend.service" &&
        action.lookup("verb") == "restart" &&
        subject.isInGroup("cryptosense-analyzer")) {
        return polkit.Result.YES;
    }
});

Note that users must belong to the cryptosense-analyzer unix group.