installation

Default set up is to run as root (default) and to lock the internal database and IPC connection socket to only root level users. This also allows using the traditional HTTPS socket (443) on systems so special firewall rules are not needed (ports below 1000 are not allow for regular processes) and TPM access if enabled. To allow other users – create a log reader group and give access to the /opt/gatoserverd/gatoserverd.sock file to it.

In order to control the service – you will also need to install the gatoshell – but it is not included in this package since users may want to collect and encrypt logs

You may run as another user if desired, but change the ownership of the /opt/gatoserverd directory to that user. All working files are created with owner only permissions. If you wish to use port 443 – you will need to configure a reverse proxy with nginx (recommended) or Apache.

This application is not provided as a Docker container since it needs local socket access, but it can be wrapped in one of the slim Ubuntu or CentOS containers if needed. Alpine Linux will not work since the glib does not contain the needed encryption support.

Ubuntu and other Debian-based Distributions

Authorize our repo:

curl -1sLf 'https://dl.cloudsmith.io/public/caprica-llc/gatodebian/setup.deb.sh' | sudo -E bash

Then install with:

apt-get update && apt-get install gatoserverd

CentOS and other RPM-based distributions

Authorize our repo:

curl -1sLf 'https://dl.cloudsmith.io/public/caprica-llc/gatorpm/setup.rpm.sh' | sudo -E bash

Then install with:

rpm -ivh gatoserverd

The software will install and will tell you how to start the service.

root@testbox:~# apt-get install gatoserverd Reading package lists...

Done Building dependency tree Reading state information... Done

Setting up gatoserverd (1.51) ... Platform systemd (default) detected. Installing service. To start this service, use: systemctl start gatoserverd

The service will create all the needed files and generate a new private key infrastructure. If using an embedded device – this may take an extended period of time but it is a one time start up.

Servers are not set to autostart by design because of the need to perform provisioning of clients before use. Enable autostart on most distributions with:

# systemctl enable gatoserverd
Created symlink /etc/systemd/system/multi-user.target.wants/gatoserverd.service → /etc/systemd/system/gatoserverd.service.
​

To start immediately – systemctl start gatoserverd.

changing gatoserverd.ini

The default configuration will work out of the box for most users. There is documentation in the file itself, as well as additional help below and in our videos on YouTube.

using gatoserverd

You cannot control the service or provision clients without the extra gatoshell application. You can temporarily or permanently install it. Embedded systems should not ship with gatoshell.

apt-get install gatoshell

or

yum install gatoshell

To connect gatod data feeders – you will need to export the key from rootca and export to them following the documentation for that projects. See more information at the gatoshell documentation(opens in a new tab)

For step by step information on loading data feeders into the servers –

/etc/gatoserverd.ini keys

port

Port is an integer indicating the port to listen to. Ports below 1000 are root only. The default is 9998. Use 443 for integration with most private cloud defaults.

gatoserver

IP address to listen on – usually 0.0.0.0 (all network interfaces) is what you want. If you have an internal network segment – use that.

gatodirectory

Where the database and other files are stored. There will my many writes – so if using an embedded media with limited lifespan (most SD cards included) – redirect to a RAM disk and add an extra service to flush at a regular time period which will work with the lifespan of your device. For regular VM systems – this isn’t an issue and the default is fine.

encrypt_tags

Applications whose data should be encrypted if enabled. This is self-reported by the apps – usually for remote applications you should use the wildcard * which means all applications. This will encrypt your log data with (almost) unbreakable encryption based on the encrypt_key tag.

encrypt_key

This is the encryption key for applications tagged with encrypt_tags entry. This is generated from the mkpem command from the shell. RSA encryption is efficient on modern hardware – so enabling this should not slow your device or server.

Note: if you lose the associated key, it is currently nearly impossible to retrieve or crack the data. It’s not impossible – but the computation cost is in the millions of dollars to do so. Save the key offline in a safe or other device.

use_tpm

Set to 1 to attempt to use a TPM 2.0 cryptographic device if installed. Be aware though this is very secure, but also will lock the encryption at rest key to that device. Using one of the test TPM software stacks is not supported – it must be a hardware device or a virtualized one exposed through your hypervisor.

Using a TPM will also create additional data files in your configuration containing the TPM configuration. The software will invoke routines in the TPM to generate a strong key stored in it which is used to encrypt sensitive data such as the at rest key. Log encryption will continue to run on the main CPU of the system.

Creating a New Device?

We do offer consultation and custom code for your IoT device, as well as logging collection on our cloud services. Contact us at sales@capricallctx.com