Single machine installation↑
On-Premises server requirements↑
Supported operating systems:
- Ubuntu 18.04 “Bionic Beaver”
- Ubuntu 20.04 “Focal Fossa”
- Red Hat Enterprise Linux 8
- Debian 11 “Bullseye”
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 / Debian↑
This installs the .deb
file:
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↑
This installs the .rpm
file and dependencies it can’t fetch from default repositories:
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:
Make sure the file is owned by the cryptosense-analyzer
user with the following command:
You can check it is correctly installed with the following command:
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:
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:
User administration↑
Adding a user↑
The command for adding a user has the following syntax:
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↑
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:
Disable the default home page:
Copy the provided configuration to the configuration directory of Nginx:
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:
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:
Disable the default home page:Copy the provided configuration to the configuration directory of Apache HTTP:
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>
Caution
Do not include any trailing slashes in the ProxyPass
target, as it could alter the S3 URLs and invalidate presigned URLs.
Allow Apache HTTP to connect to the internal application server:
Restart Apache HTTP to take the new settings into account:
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-worker-scheduler
- cryptosense-analyzer-worker-crowdstrike
- 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
- cryptosense-analyzer-worker-scheduler
- cryptosense-analyzer-worker-crowdstrike
If logging to a file is required, refer to Logging.
For instructions on sending us logs for troubleshooting, refer to Sending error logs.
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 thesystemd-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.