How to Install Modality

# For Linux

Package Contents

Installing Modality's Linux package does the following:

Installs the modality and modality-probe commands.
Installs the instrumentation SDK include files, libraries, and CMake package to default locations.
Starts the modalityd systemd service, Modality's planning and analysis daemon.
Includes an example session from an example System Under Test that you can explore from the command line.
Puts the source code for the example System Under Test in /usr/share/doc/modality/examples/c-example.

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

Install the downloaded package. After reading the EULA, press tab and then enter twice to accept and install Modality.

$ sudo apt install ./modality_<version>_<arch>.deb

Set your email address and license key with modality config. You will receive your license key by email when you request a trial of Modality.

$ modality config --license-key <license-key> --email <email-address>

To confirm that Modality installed correctly, view the log for the installed example data:

$ modality sut use example-sut && modality session use example-session
$ modality log
...
║  ║  ║  *  (494840757:14:24:8, TASK_LOOP @ CONSUMER)
║  ║  ║  ║    description="Consumer expensive task loop iteration"
║  ║  ║  ║
║  ║  ║  *  (494840757:14:24:9, TASK_LOOP @ CONSUMER)
║  ║  ║  ║    description="Consumer expensive task loop iteration"
║  ║  ║  ║
║  ║  ║  *  (494840757:14:24:10, TASK_LOOP @ CONSUMER)
║  ║  ║  ║    description="Consumer expensive task loop iteration"
║  ║  ║  ║
║  ║  ║  *  (494840757:14:24:11, TASK_LOOP @ CONSUMER)
║  ║  ║  ║    description="Consumer expensive task loop iteration"
║  ║  ║  ║

# Next steps:

To get the lay of the land, see Core Concepts.
To instrument your embedded system, see How to Instrument Your System.
To get started collecting and analyzing data explore the various guides to Using Modality.

# For Windows

Installer Contents

Modality's Windows installer does the following:

Installs the modality and modality-probe commands.
Installs the instrumentation SDK include files, libraries, and CMake package to default locations.
Starts the modalityd service, Modality's planning and analysis daemon.
Includes an example session from an example System Under Test that you can explore from the command line.
Puts the source code for the example System Under Test in /examples/c-example wherever you installed Modality.

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

Install the downloaded modality-<version>-x86_64.msi. Read and then accept the EULA to install Modality.

Set your email address and license key with modality config. You will receive your license key by email when you request a trial of Modality.

PS C:\> modality config --license-key <license-key> --email <email-address>

To confirm that Modality installed correctly, view the log for the installed example data:

PS C:\> modality sut use example-sut
PS C:\> modality session use example-session
PS C:\> modality log
...
║  ║  ║  *  (494840757:14:24:8, TASK_LOOP @ CONSUMER)
║  ║  ║  ║    description="Consumer expensive task loop iteration"
║  ║  ║  ║
║  ║  ║  *  (494840757:14:24:9, TASK_LOOP @ CONSUMER)
║  ║  ║  ║    description="Consumer expensive task loop iteration"
║  ║  ║  ║
║  ║  ║  *  (494840757:14:24:10, TASK_LOOP @ CONSUMER)
║  ║  ║  ║    description="Consumer expensive task loop iteration"
║  ║  ║  ║
║  ║  ║  *  (494840757:14:24:11, TASK_LOOP @ CONSUMER)
║  ║  ║  ║    description="Consumer expensive task loop iteration"
║  ║  ║  ║

# Next steps:

To get the lay of the land, see Core Concepts.
To instrument your embedded system, see How to Instrument Your System.
To get started collecting and analyzing data explore the various guides to Using Modality.

# Docker

Modality provides a set of Docker containers to make it easy to access advanced testing and verification features from a Docker context.

# `modality-sdk` container

Container Info

The Modality tarball containing the instrumentation SDK, CLI, and modalityd daemon is extracted in /modality.
The container url is ghcr.io/auxoncorp/modality-sdk.

This container is intended to make it easier to build with Modality in a Docker context by copying header files, libraries, and CMake utilities to your build container:

COPY --from=ghcr.io/auxoncorp/modality-sdk:latest /modality /usr/local/modality

If you are building with CMake you can follow these instructions, but you must update the CMAKE_MODULE_PATH:

list(APPEND CMAKE_MODULE_PATH "/path/to/modality/cmake")

It can be useful to run the CLI from your build container since the CLI relies on SUT definition files, which are commonly generated as part of your build. The CLI is located at /modality/bin/modality.

# Example: Docker build with Modality

# -*- mode: dockerfile -*-
FROM ubuntu:20.04
ENV DEBIAN_FRONTEND=noninteractive 
RUN apt-get update && apt-get install -y build-essential cmake

# "Install" the modality sdk via docker copy
COPY --from=ghcr.io/auxoncorp/modality-sdk:latest /modality /usr/local/modality

COPY . /src
RUN mkdir -p /src/build \
 && cd /src/build \
 && cmake -D CMAKE_MODULE_PATH=/usr/local/modality/cmake .. \
 && make

# `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

modalityd has certain networking requirements. You can configure most of these with the Modality.toml file or modality config command on the machine where you're running the CLI.

Port 14181 must be exposed for any CLI functionality to work—if you map it to a different port externally, set the modalityd config value.

$ modality config --modalityd 'http://<modalityd-container>:<port>/v1'

By default modalityd listens for reports over udp on port 2718 and over http on port 2719. To use different ports set the collector_connections config, which can accept multiple values.

$ modality config --collector-connection '<protocol>://<modalityd-container>:<collector-port>'

For scopes and mutations to work you must tell modalityd where to send control messages with the control_connections config, which can accept multiple values.

$ modality config --control-connection '<protocol>://<sut-host>:<control-port>'

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 \
    --name modalityd \
    -v "$(pwd)/modality-data-dir:/data-dir" \
    -e ACCEPT_EULA=Y \
    --network=host \
    -d --rm \
    ghcr.io/auxoncorp/modalityd:latest

# Tarball

Tarball contents

The tarball contains Modality's Instrumentation SDK, CLI, modalityd daemon, example systems, and more. The file structure is as follows:

.
├── bin
│   ├── modality
│   ├── modalityd
│   └── modality-probe
├── CHANGELOG.md
├── cmake
├── completions
├── examples
│   ├── c-example
│   └── rust-example
├── include
│   └── modality
├── lib
├── LICENSE
├── man1
├── rust
└── VERSION

If you haven't already, request a trial version of 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 start the modalityd daemon. For general usage you will likely want to run the daemon as a service. In this case we set the modalityd data-dir to the include c-example data so we can look at the example session:

$ tar xvf modality_x.y.z.tar.gz
modality_x.y.z/
...
$ cd modality_x.y.z
$ ./bin/modalityd --data-dir ./examples/c-example/data

In a new terminal, add the bin directory to your path:

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

Set your email address and license key with modality config. You will receive your license key by email when you request a trial of Modality.

$ modality config --license-key <license-key> --email <email-address>

To confirm that Modality installed correctly, view the log for the installed example data:

$ modality sut use example-sut && modality session use example-session
$ modality log
...
║  ║  ║  *  (494840757:14:24:8, TASK_LOOP @ CONSUMER)
║  ║  ║  ║    description="Consumer expensive task loop iteration"
║  ║  ║  ║
║  ║  ║  *  (494840757:14:24:9, TASK_LOOP @ CONSUMER)
║  ║  ║  ║    description="Consumer expensive task loop iteration"
║  ║  ║  ║
║  ║  ║  *  (494840757:14:24:10, TASK_LOOP @ CONSUMER)
║  ║  ║  ║    description="Consumer expensive task loop iteration"
║  ║  ║  ║
║  ║  ║  *  (494840757:14:24:11, TASK_LOOP @ CONSUMER)
║  ║  ║  ║    description="Consumer expensive task loop iteration"
║  ║  ║  ║

# Next steps:

To get the lay of the land, see Core Concepts.
To instrument your embedded system, see How to Instrument Your System.
To get started collecting and analyzing data explore the various guides to Using Modality.

# Updating Modality

Use modality --version to see the version of Modality installed on your system. You can check if there is a new version on the Modality download page. (opens new window) To update Modality, follow the platform-specific installation steps above. Updating Modality will not delete or modify your existing data.

← Core Concepts Modality Basics →

How to Install Modality

# For Linux

# Next steps:

# For Windows

# Next steps:

# Docker

# modality-sdk container

# Example: Docker build with Modality

# modalityd container

# Example: Run modalityd container

# Tarball

# Next steps:

# Updating Modality

# `modality-sdk` container

# `modalityd` container

# Example: Run `modalityd` container