How to Install Modality
# For Linux
Package Contents
Installing Modality's Linux package does the following:
- Installs the
modality
andmodality-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
andmodality-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 /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 withdocker 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.