How to Install Modality

# For Linux

Results

Following these steps results in the following:

  • Installs the modality command for data management and analysis.
  • Installs the modality-reflector command for data collection.
  • Installs the current set of reflector plugins for data collection.
  • Starts the modalityd systemd service, Modality's data management and analysis daemon.

If you haven't already, request a license key for Modality. (opens new window) Auxon will email you a Modality license key. Then download Modality for Linux. (opens new window)

Install the downloaded setup package.

$ sudo dpkg -i auxon_$VERSION_all.deb

Update your apt repositories, then install the packages for the Modality daemon, CLI, and data collection. After reading the EULA, press tab and then enter twice to accept and install Modality.

$ sudo apt-get update
$ sudo apt-get install modalityd modality-client modality-reflector

Set your license key in the modalityd config file. By default this file is located at /etc/modalityd/config.toml and should be created when you install the modalityd package.

# /etc/modalityd/config.toml

# default data-dir
data-dir = '/var/lib/modality'

# your license key
license-key = '000000-000000-000000-000000-000000-V3'

# Next steps:

# Docker

Modality provides a set of Docker containers to make it easy to collect and analyze data from a Docker context.

# modalityd container

Container Info

  • This container is intended to make it easy to run the modalityd daemon with docker run.
  • The container url is ghcr.io/auxoncorp/modalityd.

There are several considerations when running this container.

The modality data directory is expected to be mounted to /data-dir as a volume:

-v "$(pwd)/modality-data-dir:/data-dir"

The environment variable ACCEPT_EULA must be set to Y. You can read the EULA here.

-e ACCEPT_EULA=Y

The environment variable MODALITY_LICENSE_KEY must contain a valid license key. If you haven't already, request a license key for Modality. (opens new window) Auxon will email you a Modality license key.

-e MODALITY_LICENSE_KEY=`cat ~/.config/modality_license`

You must either set the TLS_CERT and TLS_KEY environment variables for secure TLS connections, or you must set NO_TLS to allow modalityd to run with insecure connections.

-v "$(pwd)/certs:/certs" \
-e TLS_CERT=/certs/modality.crt \
-e TLS_KEY=/certs/modality.key \

modalityd serves its API (for the modality analysis CLI) over HTTP on port 14181 for insecure connections and over HTTPS on port 14183 for secure connections. You must therefore make sure the corresponding port is exposed, depending on whether you set the TLS environment variables or not.

-p 14183:14183

modalityd listens for incoming data on port 14182 for insecure connections and on port 14184 for secure connections. You must therefore make sure the corresponding port is exposed, depending on whether you set the TLS environment variables or not.

-p 14184:14184

In this example we use the --network=host option to expose the required ports as-is. You could also use the -p option to map the ports according to your networking needs.

# Example: Run modalityd container

docker run \
  -v "$(pwd)/modality-data-dir:/data-dir" \
  -v "$(pwd)/certs:/certs" \
  --network=host \
  -e MODALITY_ACCEPT_EULA=Y \
  -e MODALITY_LICENSE_KEY=`cat ~/.config/modality_license` \
  -e TLS_CERT=/certs/modality.crt \
  -e TLS_KEY=/certs/modality.key \
  -d --rm \
  ghcr.io/auxoncorp/modalityd:latest

# modality-reflector container

Container Info

  • This container is intended to make it easy to run a reflector with docker run.
  • The container url is ghcr.io/auxoncorp/modalityd-reflector.

There are several considerations when running this container.

For the container to receive any data you must make sure its protocol-child-port (specified in the configuration file) is exposed.

-p 14188:14188

modality-reflector requires an authentication token with the allow-ingest permission to collect data. The CLI reference has more information on auth tokens. For Docker purposes, you can either set the MODALITY_AUTH_TOKEN environment variable or put a valid auth token file in the container, either in the default place or pointed to with the --auth-token-file option.

-e MODALITY_AUTH_TOKEN=`cat ~/.modality-reflector-auth-token`

If you would like the reflector to be allowed to communicate with modalityd over insecure connections, set the INSECURE environment variable.

-e INSECURE

You must set either the MODALITY_HOST or INGEST_PROTOCOL_PARENT_URL environment variable to tell the reflector where to send its collected data.

-e INGEST_PROTOCOL_PARENT_URL=modality-ingest-tls://auxon.io:14184

If you set MODALITY_HOST the connection will be made over tls, on the default port (14184). If both variables are set the INGEST_PROTOCOL_PARENT_URL will take precedence.

WARNING

If you would like to communicate over insecure connections you must set the INGEST_PROTOCOL_PARENT_URL. If you use MODALITY_HOST the protocol parent URL will be set to a tls protocol and insecure connections will fail.

Use the REFLECTOR_OPTS environment variable to pass any additional options to the modality-reflector run command. At a minimum this will typically include a config file and options specifying which collector plugins to run.

-v "$(pwd)/modality-reflector-config:/reflector-config"
-e REFLECTOR_OPTS='--config /reflector-config/my-config.toml --all-collectors'

# Example: Run modality-reflector container

docker run \
  -p 14188:14188 \
  -e MODALITY_HOST=auxon.io \
  -v "$(pwd)/modality-reflector-config:/reflector-config" \
  -e MODALITY_AUTH_TOKEN=`cat /reflector-config/.modality-reflector-auth-token` \
  -e REFLECTOR_OPTS='--config /reflector-config/my-config.toml --all-collectors' \
  -d --rm \
  ghcr.io/auxoncorp/modality-reflector:latest

# Tarball

Tarball contents

The tarball contains Modality's modalityd daemon, the Modality CLI, data collection infrastructure, example systems, and more. The file structure is as follows:

.
├── bin
│   ├── conform
│   ├── modality
│   ├── modalityd
│   ├── modality-reflector
│   └── modality-probe
├── CHANGELOG.md
├── cmake
├── completions
├── examples
│   ├── c-example
│   └── rust-example
├── include
│   └── modality
├── lib
├── LICENSE
├── man1
├── modality-reflector-config.toml
├── modality-reflector-plugins
│   ├── collectors
│   └── importers
├── python
├── rust
└── VERSION

If you haven't already, request a license key for Modality. (opens new window) Auxon will email you a Modality license key. Then download the tarball. (opens new window)

EULA

By downloading or using Modality, you are agreeing to be bound by the terms and conditions of the EULA.

Extract the downloaded tarball and create a modalityd config file with the license key you received by email. The standard location for this file is /etc/modalityd/config.toml:

# /etc/modalityd/config.toml

# Your license key here
license-key = '000000-000000-000000-000000-000000-V3'

# Standard data directory for modalityd running as a service
data-dir = '/var/lib/modality'

Start the modalityd daemon. For general usage you will likely want to run the daemon as a service.

$ tar xvf modality_x.y.z.tar.gz
modality_x.y.z/
...
$ cd modality_x.y.z
$ ./bin/modalityd

In a new terminal, add the bin directory to your path (you will likely want to update your relevant shell configuration to always set this):

$ export PATH=$PATH:/path/to/modality_x.y.z/bin

# Next steps:

← Tutorial →