gatod

installation

gatod functions as a forwarding agent for logging data. It performs encryption of the traffic and also manages the encryption keys needs to access the main system (gatoserverd) over the network. It has two operating modes – both of which can be used simulatanously if needed. It has no local data storage other than a ‘checkpoint’ file which is used to keep track of the last records sent in log reader mode.

gatod can act as a syslog replacement/add-on and can listen on a local socket. To run on a socket below 1000 it must run as root (the default). The default port is 9999.
gatod can work as a log reader – which it will periodically scan the main syslog file. This will require a checkpoint file be written into the gatod_directory. Note: for IoT devices – you should probably symlink this file (syslog.lck) to a RAM disk to extend your storage life

During the set up process – you will need to use the gatoshell on the logging server to mint a certificate to allow access. Although it is possible to use the same certificate on all devices – this is not a good practice in you may need to eventually block some devices if they become compromised or show field defects and emit excessive events. The manufacturing and set up process can automated to generate unique keys for all nodes – as well as IP address metering on your data center. If implementing at scale – contact us for OEM support and managed back end services for data collection and manufacturing.

The software will install a sample gatod.ini in your /etc directory. This can be moved into the same directory as the software for custom installs.

Important: you will need to cut and paste certificates in PEM format – the certificate is everything and including header and footer lines which include a series of dashes (—). The lines with dashes need to be included.

Ubuntu and other Debian-based Distributions

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

apt-get install gatod

CentOS and other RPM-based distributions

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

rpm -ivh gatod

provisioning keys for server access

After installing the software, run it once as root or the end user account. It will generate a set of unique keys for the node and output instructions for linking to the server.

2021/09/26 06:34:22 Searching for ./gatod.ini
2021/09/26 06:34:22 Attemping to load ./gatod.ini
2021/09/26 06:34:22 ⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯
2021/09/26 06:34:22 gatod copyright © 2021 caprica llc tx - all right reserved
2021/09/26 06:34:22                 Version 1.9999
2021/09/26 06:34:22 ⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯
2021/09/26 06:34:22 Local Listening Port: 9999
2021/09/26 06:34:22 Gato Server         : localhost
2021/09/26 06:34:22 Gato Directory      : ./
2021/09/26 06:34:22 Gato Server Port    : 443
2021/09/26 06:34:22 Gato Security       : DISABLED
2021/09/26 06:34:22 No license found
2021/09/26 06:34:22 This client needs to be registered - log into the main server and run gatoshell.
2021/09/26 06:34:22 Run license and enter the following when prompted.  Save the result into the config dir
2021/09/26 06:34:22 As gato.crt
2021/09/26 06:34:22 
-----BEGIN CERTIFICATE REQUEST-----
MIIE0TCCArkCAQAwZTELMAkGA1UEBhMCVVMxCzAJBgNVBAgTAlRYMRAwDgYDVQQH...

Cut and paste the data between and including the tags:

Then a response will be generated with a response you will need to save as gatod.crt in your configuration directory (default /etc/gatod):

>>> license
Paste the license into the terminal
-----BEGIN CERTIFICATE REQUEST-----
MIIE0TCCArkCAQAwZTELMAkGA1UEBhMCVVMxCzAJBgNVBAgTAlRYMRAwDgYDVQQH
<many lines here not printed in this document>
-----END CERTIFICATE REQUEST-----

While in the shell – also run and save the output from rootca, this will be identical in all systems so you really only need to do this once. Save this certificate as rootca.crt in the configuration directory. If you skip this step – you will be prompted too on next run of gatod.

gatod.ini

You can override the default search path for this file with the command line option -c. INI files are case sensitive inside

log_reader

Set to 0 to disable reading/forwarding local syslog. Enabled by default.

port

Set to 0 to disable local listener – default is 9998.

gatoserver

DNS name of the server running the gatoserverd service. IP addresses are not valid here – the top level certificates do not contain IP address SANs to prevent leaking network topology. If your network does not have DNS – update the hosts file on the servers to allow names to resolve.

gatoserver_port

DNS name of the server running the gatoserverd service – usually will be 443 if your network rules only allow https, or 9998.

gatod_directory

This directory will contain the certificates for this node, as well as a file named syslog.lck which is written to periodically if log reading is enabled.