Datagrid Telemetry Client (standalone)

Installation

RPM from yum repository

The telemetry client package is installable on most OS-es that use RPM packages, including CentOS 5/6/7, Red Hat, Fedora, Amazon Linux and SuSE.

It can be found in the Datagrid yum repository:

https://s3.amazonaws.com/dgri-rpm-repo/x86_64/

(the client software is architecture-independend and can be installed and ran on 32-bit systems, as well)

The following command will add the Datagrid repository to your yum repositories list:

sudo rpm -U https://s3.amazonaws.com/dgri-bits/download/dgri-rpm-repo-latest.noarch.rpm

Now, the telemetry client can be installed or upgraded with yum:

sudo yum install -y dgri-report

Deb package from apt repository

Add the Datagrid apt repository to your system:

wget https://s3.amazonaws.com/dgri-bits/download/dgri-apt-repo_latest_all.deb
sudo dpkg -i dgri-apt-repo_latest_all.deb

or add the deb line directly to a package list file:

echo 'deb https://s3.amazonaws.com/dgri-apt-repo/ production main' | \
sudo tee /etc/apt/sources.list.d/dgri.list >/dev/null

Add the signing key:

wget https://s3.amazonaws.com/dgri-apt-repo/datagrid.key
sudo apt-key add datagrid.key

The repository is accessed over https, so on some systems you may need to add this, as well:

sudo apt-get install apt-transport-https ca-certificates

Now, update the apt database and install the telemetry client:

sudo apt-get update
sudo apt-get -y install dgri-report

Upgrade

NOTE: when upgrading from version 1.18 and earlier, it is necessary to un-install and re-install the package, as follows:

Deb package:

sudo rm -f /tmp/dgri_*.json
sudo apt-get remove dgri-report
sudo apt-get update
sudo apt-get install dgri-report
sudo dgri-report-setup

RPM package:

sudo rm -f /tmp/dgri_*.json
sudo yum erase dgri-report
sudo yum install install dgri-report
sudo dgri-report-setup

The uninstall/reinstall procedure will not delete your existing configuration. It will re-make the cron configuration, which will randomize the check and report schedule. The upgraded version will no longer run the cron job as root, unless you use the --root option when running dgri-report-setup

If you have a version newer than 1.18, the client can be upgraded using the normal package manager upgrade commands:

Deb:

sudo apt-get update
sudo apt-get install dgri-report
#or: sudo apt-get dist-upgrade # to upgrade all packages

RPM:

sudo yum upgrade dgri-report
#or: sudo yum upgrade # to upgrade all packages

Configuration

The client requires telemetry (feed) credentials for your account to be able to work. If your site is using the Datagrid Anonymization Gateway, the location of the gateway also needs to be configured.

Run the following command:

sudo dgri-report-setup feed_url=https://feed.datagridsys.com/ \
    feed_username=your_telemetry_username

(replace the url with https://your-gateway.example.com:8081/ if using a gateway)

Enter the password when prompted.

Use

Once configured, the client will be ran automatically by cron and does not require any intervention. The cron schedule is chosen randomly when you first run dgri-report-setup, as follows:

  • once an hour, at a random minute, the host configuration is checked and if it changed since the last run, or if the system has rebooted or if this is the first run ever, a report is sent.
  • once a day, at the same random minute, if nothing has changed, a 'ping' signal is sent.

Whenever the client sends anything to Datagrid (or to the gateway, if configured), it will leave a record of the data sent in /tmp:

/tmp/dgri_collect.json   - the last sent configuration report
/tmp/dgri_signal.json    - the last sent ping signal

Advanced

Command Line Interface

Command summary:

dgri-report-setup [--root] [option=value .... ]

dgri-report signal signalname [option=value .... ]

dgri-report collect [option=value .... ]

dgri-report-setup saves the options given on the command line persistently and configures a cron job to run dgri-report periodically. Except for specialized setups (see the following sections), this command should be ran as root, after installing the rpm or deb package. The settings given on the command line or at the interactive prompt displayed by dgri-report-setup will be remembered and used when dgri-report is ran either automatically from cron or manually (unless overridden by an explicit new setting on the command line). By default, the cron job is set up to run as the user dgri-report. To set up dgri-report to run as root instead, use the --root option. It is recommended to use the --root option if your system does not have sudo installed.

dgri-report signal sends a short signal message. The signal name can be any string. The following names are recognized:

ping - the 'system alive' signal. It is sent automatically when dgri-report-setup is ran with on_unchanged_config=ping, if the configuration has not changed.

reboot - report a reboot.

In addition, the following signal names are reserved:

crash, logerror, offline, rollback, test_success, user_success, online, test_fail, user_fail

The accepted options are:

feed_url - where to send the telemetry reports. Default: https://feed.datagridsys.com/. Note this default will not be used automatically if you do not specify feed_url, but it will be offered as the value to use if you enter the empty string at the interactive prompt, when running dgri-report-setup.

feed_username, feed_password - the telemetry credentials. NOTE it is best not to specify the password on the command line. Use dgri-report-setup without giving a password (or if one is already configured and you want to enter a different one, give an empty password on the command line). The command will display a password prompt and read the password from the console.

on_unchanged_config - used only with the collect action. Specifies what to do if the current configuration is the same as on the previous run of dgri-report collect. Valid values are: nop (do nothing at all), ping (send a ping signal instead of a configuration report) and send (send the config report - this is the default).

advoptions - a comma-separated list of strings. These options are used to disable or modify parts of the data collection sequence. Do not use this unless instructed by Datagrid support.

Configuration File

The client reads configuration from ~/.dgri-report.conf or, if that file does not exist, from /etc/dgri-report.conf.

When the dgri-report-setup command is used, it will write to /etc/dgri-report.conf, if ran as root. Otherwise, it will write to ~/.dgri-report.conf.

Disabling Periodic Reports, Custom Report Scheduling

The periodic reporting is configured with dgri-report-setup. To configure dgri-report for manual execution or for control by tools other than cron, skip running the dgri-report-setup command. Instead, the configuration settings should be saved into /etc/dgri-report.conf using a text editor or any other method for creating this file. The file can contain any of the key=value options described in the command line interface section, one setting on a line.

If dgri-report-setup was already ran and you want to disable the periodic reporting, move or delete the cron file, e.g.:

sudo mkdir -p /etc/cron.disabled
sudo mv /etc/cron.d/dgri-report /etc/cron.disabled

(to re-enable, move the dgri-report file back into /etc/cron.d)

To run a system check and send a configuration report, if anything has changed:

dgri-report collect on_unchanged_config=nop

(this is the default hourly cron command)

To run a system check and send either a configuration report or a ping signal if nothing has changed:

dgri-report collect on_unchanged_config=ping

To send a config report, regardless of changes:

dgri-report collect

To report the system as being alive, without checking for or reporting configuration changes:

dgri-report signal ping

Security

To minimize possible impact on your system, the default setup configures dgri-report to run as a regular user (not as root). To allow for this, the following changes are made to the OS configuration when you run dgri-report-setup without using the --root option:

  • a new dgri-report user is created, with home directory in /var/lib/dgri-report. This user has no valid login password and its default shell is nologin (or /bin/false, if nologin does not exist), so it cannot be easily used to access the system interactively.
  • the dgri-report user is given sudo permission to execute /bin/cat /sys/devices/virtual/dmi/id/* (only this specific command is added as allowed, no other sudo privileges are given to dgri-report).
  • if a group docker exists, it is added as a member of this group. This is done only when running dgri-report-setup. If you did not have Docker installed at that time, but add it later, the dgri-report user will not be member of the docker group. IMPORTANT: being a member of the docker group gives the user effective sudo permission to run any command as root. If this is a concern, you can remove dgri-report from the group after the intial setup. Note that this will prevent it from gathering container telemetry.

User-only Setup

If you have a user account that is allowed to set up and use cron jobs and want to use it instead of using the dgri-report user created by the setup utility, the client can be configured to run automatically from cron and run without being root. If you choose to do this, do not run dgri-report-setup as root after installing the package.

Instead, log in as the user that you want to use for running dgri-report and run:

dgri-report-setup

(answer the interactive prompts to complete the setup)

NOTES:

  • The above command will delete any crontab that you may have had for the current user.
  • The crontab created when running dgri-report-setup without being root will not be deleted if you un-install the package, you will have to do it yourself with crontab -r.
  • If you use Docker containers on the system: unless your user account is a member of the docker group, dgri-report will not be able to get container information and therefore will not send any telemetry data for containers.
  • Setting up in this manner will prevent dgri-report from reading the /sys/devices/virtual/dmi/id/product_uuid file. This can cause a failure, if no other reliable unique identifier can be found for your system. To give the user permission to read the file, add this to your sudoers file:
    your_username ALL = (root) NOPASSWD: /bin/cat /sys/devices/virtual/dmi/id/*