Configuration¶

MTDA will attempt to read the following configuration files (and in that order):

/etc/mtda/config

/etc/mtda/config.d/*.conf

$HOME/.mtda/config

Most recently loaded configuration items take precedence over others. This allows a regular user to override system defaults.

Configuration files are similar to what’s found in Microsoft Windows INI files (Python’s configparser module is used to parse them).

It is possible to override some settings using environment variables.

General settings¶

main: section [optional]
Usually placed at the top of MTDA configuration files. It contains general settings.
- debug: integer [optional]
  Level of debug messages to print out while running (set to 0 to turn all debug messages off).
- name: string [optional]
  Name of this agent on the network (defaults to hostname).
pastebin: section [optional] Support for posting console content to services like pastebin.com. An API key is required and may be specified with:
- api-key: string [optional] Define the API key to be passed to the pastebin service
- endpoint: string [optional] Specify an alternate pastebin service (defaults to http://pastebin.com/api/api_post.php)
ui: section [optional] User Interface settings for the console. This is relevant only for MTDA clients.
- prefix: string [optional]
  Change the key prefix to control the interactive MTDA console. The default prefix is ctrl-a (which is also used by the screen tool, this setting may be used to use e.g. ctrl-b instead).
console: section [optional]
Specify console settings when running the agent-side of MTDA (this section is ignored when running MTDA as a client). The variant key should be set, other settings in this section are variant-specific.
- variant: string [required]
  Select a console variant. MTDA provides the following drivers: serial and telnet.
keyboard: section [optional]
Specify a keyboard driver.
- variant: string [required]
  Select a keyboard driver between hid and qemu.
monitor: section [optional]
Specify settings for the monitor console when running the agent-side of MTDA (this section is ignored when running MTDA as a client). The variant key should be set, other settings in this section are variant-specific.
- variant: string [required]
  Select a console variant. MTDA provides the following drivers: serial and telnet.
power: section [optional]
Configure a power controller for the device attached to MTDA. The driver may be selected with variant.
- variant: string [required]
  Select a power variant from aviosys_8800, anel, gpio, pduclient, qemu, shellcmd and usbrelay.
remote: section [optional]
Specify the host and ports to connect to when using a MTDA client (such as mtda-cli).
- control: integer [optional]
  Remote port listening for control commands (defaults to 5556).
- console: integer [optional]
  Remote port to connect to in order to get console messages (defaults to 5557).
- data: integer [optional]
  Remote port for data transfers between the client and agent (defaults to 0 for a dynamic port assignment).
- host: string [optional]
  Remote host name or ip to connect to as a client to interact with the MTDA agent (defaults to localhost).
scripts: section [optional]
Python scripts to be executed upon certain events. Use ``… `` instead of hard/soft spaces to preserve indentation.
- power off: string [optional]
  Execute a Python script when the device is powered off.
- power on: string [optional]
  Execute a Python script when the device is powered on such as the following:
  if 'boot-from-sd' in env and env['boot-from-sd'] == '1': ... mtda.monitor_wait("Hit any key to stop autoboot") ... mtda.monitor_send(" ") ... mtda.monitor_send("run bootcmd_mmc0\n")
  This sample script would instruct MTDA to wait for the Hit any key to stop autoboot on the monitor interface before sending a space and sending a custom boot command.
storage: section [optional]
Configure a shared storage driver that may be swapped between the device attached to MTDA and the host running the agent. The driver will be selected with variant.
- variant: string [required]
  Select a shared storage variant from docker, qemu, samsung, usbsdmux and usbf.
usb: section [optional]
Specify how many USB ports may be controlled from this agent.
- ports: integer [optional]
  Number of USB ports. Each port should then be configured with its own [usbN] section where N is the port index (starting from 1).
video: section [optional]
Configure a video capture driver to stream what is displayed on the Device Under Test. The driver will be selected with variant.
- variant: string [required]
  Select a video variant: mjpg_streamer (deprecated) or ustreamer
www: section [optional]
A lightweight web server will be started when this section is present. The following parameters may be customized:
- port: integer [optional]
  Port to run the HTTP service on (defaults to 5000).
- host: string [optional]
  Host address to listen on. This defaults to 127.0.0.1 to only accept connections from the machine running the MTDA service. Change to 0.0.0.0 to accept connections from anywhere.

Console, Monitor & Keyboard settings¶

The [console] and [monitor] sections respectively configure the user and monitor consoles for interacting with the device under test. The monitor console is optional (most devices have a single console). Data received on the user console will be streamed to MTDA clients while data received from the monitor interface will be logged in a ring buffer (that clients may read). For both consoles, the driver is selected with the variant setting. Options specific to each driver are documented below.

`docker` driver settings¶

Use the docker console driver when the power driver is also set to docker. This driver will interact with the selected container over a docker socket. There are no further settings for this driver.

`qemu` driver settings¶

Use the qemu console driver when the power driver is also set to qemu. This driver will interact with the emulated serial device. There are no further settings for this driver.

`serial` driver settings¶

The serial driver may be used when the device uses a serial console. The following may be configured:

port: string [required]
Path to the serial device on the host running the MTDA agent (for example /dev/ttyS0).
rate: integer [optional]
The baud rate used by the device to communicate with the MTDA agent. This setting defaults to 115200.

`telnet` driver settings¶

Some power distribution racks also include serial interfaces that are exposed to remote clients via telnet. Some debug boards may also be attached to custom hardware designs. The telnet driver may be used in such configurations and supports the following settings:

host: string [required]
Hostname of the telnet server.
port: integer [optional]
The port on which the telnet server is running (defaults to 23).
delay: integer [optional]
Time interval (in seconds) to wait for before trying to reconnect to the telnet server (defaults to 5 seconds).
timeout: integer [optional]
Timeout (in seconds) for each connect.

`hid` driver settings¶

The hid driver emulates keyboard presses via the usbf driver:

device: string [optional]
Name of the kernel hid device (default: /dev/hidg0). The device will be created on use.

Power settings¶

The [power] section configures a power controller to power the device on or off. The driver is selected with the variant setting. Driver-specific settings are detailed below.

`aviosys_8800` driver settings¶

The aviosys_8800 driver supports the USB controller power outlet from Aviosys. The following settings are supported:

pid: integer [optional]
The USB product ID of the power outlet (defaults to 2303).
vid: integer [optional]
The USB vendor ID of the power outlet (defaults to 067b).

`anel` driver settings¶

The anel driver supports the UDP API of the Ethernet controlled power strips from Anel. The following settings are supported:

host: string [required]
The IP or hostname of the power strip.
plug: integer [required]
The number of the plug used.
user: string [optional]
The username as configured in the web interface (defaults to admin).
password: string [optional]
The password as configured in the web interface (defaults to amel).
port_in: integer [optional]
The receive port of the UDP api as configured in the web interface (defaults to 77).
port_out: integer [optional]
The send of the UDP api as configured in the web interface (defaults to 75).

`docker` driver settings¶

The docker driver may be used to use a docker container instead of a physical device. The following settings are supported:

image: string [optional]
The docker image to use for this container. This setting defaults to alpine.
command: string [optional]
The command to execute when the container is started. The default command is sh.

`gpio` driver settings¶

The gpio driver may be used to control a simple electric relay using GPIO lines from the system running the MTDA agent. The following settings are supported:

gpio: string [required]
Specify the GPIO line(chip) and pin number which will be used to control the relay. Format: <gpiochipx>@<pin> If multiple GPIO lines and pins are used separate the entries using ‘,’.

enable: string [optional]

If the relay enable trigger is high or low. Defaults to high.

Example:

# For single GPIO line
gpio = gpiochip0@201
enable = high
# For multiple GPIO lines
gpio = gpiochip0@201,gpiochip1@11,gpiochip0@203

`pduclient` driver settings¶

The pduclient driver may be used to let a LAVA instance control the power of the device attached to MTDA. The following settings are supported:

daemon: string [required]
Determines the hostname of the hostname which is running lavapdu-listen to which the MTDA agent can connect to and send power commands.
hostname: string [required]
The PDU which will run power commands sent by the MTDA agent.
port: integer [required]
The port on the specified PDU to which the device is connected.

`qemu` driver settings¶

The qemu driver may be used to use QEMU/KVM instead of a physical device. The following settings are supported:

bios: string [optional]
The BIOS to be loaded by QEMU/KVM.
cpu: string [optional]
The CPU to be emulated by QEMU/KVM.
smp: integer [optional]
smp=<NUMBER> specifies the number of cores the guest is permitted to use. The number can be higher than the available cores on the host system. Use smp=0 to use all currently available cores.
executable: string [optional]
The QEMU/KVM executable to use as system emulator. This setting defaults to kvm
hostname: string [optional]
Name of emulated machine to be provided by QEMU/KVM internal DHCP server.
machine: string [optional]
The QEMU/KVM machine to emulate.
memory: integer [optional]
The amount of memory (in mega-bytes) for the emulated machine (defaults to 512 MiB).
pflash_ro: string [optional]
Path to the read-only firmware flash.
pflash_rw: string [optional]
Path to the read-write firmware flash.
storage: string [optional]
Path to the emulated machine storage. Use storage.0, storage.1, etc. if more than one system drive should be emulated.
storage.size: integer [optional]
Size in GB for emulated machine storage. Use storage.0.size, storage.1.size, etc. if more than one system drive should be emulated.

Note an existing storage device will not be recreated or deleted based on a config change. To trigger recreation delete your storage devices manually.
swtpm: string [optional]
Path to the swtpm binary to support emulation of a TPM device.
watchdog: string [optional]
Name of the watchdog driver provided by QEMU/KVM for the selected machine.

`shellcmd` driver settings¶

The shellcmd driver may be used to control power switch with custom shell commands, e.g. curl requests:

on-cmd: string [required]
Power-on shell command. The return code should be 1 on success.
off-cmd: string [required]
Power-off shell command. The return code should be 1 on success.
check-on: string [required]
Shell command to check the power state. Should return 0 if power is on, 1 if it is off. Any other return code is interpreted as error.

`usbrelay` driver settings¶

The usbrelay driver may be used to control USB HID relays attached to the system running the MTDA agent. The following settings are supported:

lines: string [required]
Comma separated list of lines to toggle relays driving power of the device.

Shared storage settings¶

The [storage] section configures a shared storage device that may be used either from the device under test or from the host running the MTDA agent. The driver is selected with the variant setting. Driver-specific settings are detailed below.

`samsung` driver settings¶

The samsung driver supports both SD Mux and SD Wire and may used to share a SD card between the DUT and host. The following settings are supported:

device: string [optional] Block device for the shared storage as seen on the host (defaults to /dev/sda)
serial: string [optional] Identifier of the sdmux/sdwire device to use. Use sd-mux-ctrl to list available devices. When not specified, the first device is auto-detected.

`usbsdmux` driver settings¶

The usbsdmux driver supports SD card switcher based on the Microchip USB2642 card reader chip. A tool with this name is available for several distributions and via pip. The following settings are supported:

device: string [optional] Block device for the shared storage as seen on the host (defaults to /dev/sda)
control-device: string [optional] Control device used for talking to the switcher on the host (defaults to /dev/sg0)

`usbf` driver settings¶

The usbf driver adds a Mass Storage function to the USB composite configuration to expose either a file or a physical device or partition to the DUT as a Mass Storage device. The following settings are supported:

device: string [optional] Block device for the shared storage as seen on the host. A systemd dependency is added to ensure the service is started only after the specified block device was found. A warning is issued if the input is not a block device.
cow: string [optional] Block device to receive writes to the shared storage in lieu of the source device. Changes may be either committed or reverted.
file: string [optional] File for the shared storage: a loopback device will be created to make sure that writes to the shared storage do not cause this file to expand and leave the host without free space. If the file does not exist, it is automatically created with a fixed size of 8GB. It also can be created manually by running truncate -s 2G storage.img.

Network settings¶

The [network] section configures a controllable network link between the agent and the device under test. The driver is selected with the variant setting. Driver-specific settings are detailed below.

`usbf` driver settings¶

The usbf driver adds an ECM function to USB composite device exposed to the DUT. The following settings are supported:

dhcp: boolean [optional] Whether to offer an IPv4 address to the Device Under Test (defaults to true)
forward: string [optional] A comma separated list of NAT forwarding rules from the agent to the Device Under Test. Each rule is of the form <protocol>:<agent-port>:<device-port> with protocol being either tcp or udp. Example: tcp:2222:22,tcp:8080:80 to forward SSH and HTTP requests received on ports 2222 and 8080 respectively to ports 22 and 80 on the Device.
gateway: boolean [optional] Whether to act as a gateway and forward traffic from the Device Under Test to remote (e.g. Internet) hosts (defaults to true)
ipv4: string [optional] The IPv4 address to be set when the network interface is brought up (defaults to 192.168.7.1/24)
peer: string [optional] The IPv4 address of the Device Under Test. (defaults to the next IPv4 address after the address set with the ipv4 setting).

Timeout settings¶

The [timeouts] section allows various timeouts to be configured:

lock: integer [optional] Automatically release the DUT after the specified number of minutes.
power: integer [optional] Automatically power off the DUT if there are no active sessions. Use 0 to disable.
session: integer [optional] Mark a session inactive after the specified number of minutes.

Video capture settings¶

The [video] section configures a video capture device to stream the contents of the device display. The driver is selected with the variant setting. Driver-specific settings are detailed below.

`mjpg_streamer` driver settings¶

The mjpg_streamer driver supports Webcams and video capture devices such as the Tihokile HDMI capture dongle. The following settings are supported:

device: string [optional] Video device to grab MJPEG images from (defaults to /dev/video0)
port: integer [optional] HTTP port to serve on (defaults to 8080)
resolution: string [optional] Resolution of the video stream (defaults to 1280x780)
www: string [optional] Path to static web pages to serve (defaults to /usr/share/mjpg-streamer/www)

Point VLC (or similar) to http://<mtda-ip-or-name>:8080/?action=stream to stream video from the Device Under Test.

`qemu` driver settings¶

The qemu driver may be used with clients supporting the RFB (VNC) protocol. The following settings are supported:

sink: string [optional] GStreamer sink element to be used on the client-side for rendering

The url() method of the driver will return the GStreamer pipeline to be used on the client side.

Configuration¶

General settings¶

Console, Monitor & Keyboard settings¶

`docker` driver settings¶

`qemu` driver settings¶

`serial` driver settings¶

`telnet` driver settings¶

`hid` driver settings¶

Power settings¶

`aviosys_8800` driver settings¶

`anel` driver settings¶

`docker` driver settings¶

`gpio` driver settings¶

`pduclient` driver settings¶

`qemu` driver settings¶

`shellcmd` driver settings¶

`usbrelay` driver settings¶

Shared storage settings¶

`samsung` driver settings¶

`usbsdmux` driver settings¶

`usbf` driver settings¶

Network settings¶

`usbf` driver settings¶

Timeout settings¶

Video capture settings¶

`mjpg_streamer` driver settings¶

`qemu` driver settings¶

MTDA

Navigation

Related Topics

Configuration¶

General settings¶

Console, Monitor & Keyboard settings¶

docker driver settings¶

qemu driver settings¶

serial driver settings¶

telnet driver settings¶

hid driver settings¶

Power settings¶

aviosys_8800 driver settings¶

anel driver settings¶

docker driver settings¶

gpio driver settings¶

pduclient driver settings¶

qemu driver settings¶

shellcmd driver settings¶

usbrelay driver settings¶

Shared storage settings¶

samsung driver settings¶

usbsdmux driver settings¶

usbf driver settings¶

Network settings¶

usbf driver settings¶

Timeout settings¶

Video capture settings¶

mjpg_streamer driver settings¶

qemu driver settings¶

`docker` driver settings¶

`qemu` driver settings¶

`serial` driver settings¶

`telnet` driver settings¶

`hid` driver settings¶

`aviosys_8800` driver settings¶

`anel` driver settings¶

`docker` driver settings¶

`gpio` driver settings¶

`pduclient` driver settings¶

`qemu` driver settings¶

`shellcmd` driver settings¶

`usbrelay` driver settings¶

`samsung` driver settings¶

`usbsdmux` driver settings¶

`usbf` driver settings¶

`usbf` driver settings¶

`mjpg_streamer` driver settings¶

`qemu` driver settings¶