IOR

Overview

IOR is a parallel I/O benchmark commonly used to measure read and write performance on HPC and scale-out storage systems. The bundled runner distributes MPI ranks across multiple client hosts so you can measure the maximum aggregate read and write performance of a distributed storage system.

Official Resources

• IOR documentation
• IOR source repository

Prerequisites

• Install the mass-client package on every participating test host.
• Mount the same DAOS filesystem on every participating client. The runner uses the mount specified by DFS_PATH to resolve the pool and container, then runs IOR through the DFS backend.

note

For Storage resource provisioning, see Managing Storage. For mass-client installation instructions, see CLI Reference.

Running IOR on MASS

MPI rank

MPI rank refers to a process that sends I/O requests. NPROCS specifies the number of these processes to run on each node. For a multi-node test, the total number of processes is NPROCS multiplied by the number of hosts.

For example, HOSTS=client01,client02 NPROCS=16 runs 16 processes on each node and 32 processes in total, with each process sending I/O requests.

1. Run a single-node test:

NPROCS=16 DFS_PATH=/mnt/poc-home \
  /opt/boostx-sds/ior/scripts/ior.sh

2. To measure aggregate performance across multiple clients, provide a comma-separated host list. NPROCS is the number of ranks per host:

HOSTS=client01,client02,client03,client04 NPROCS=16 DFS_PATH=/mnt/poc-home \
  /opt/boostx-sds/ior/scripts/ior.sh

The multi-node launcher requires passwordless root SSH between the participating hosts and the same MASS client installation on every host. If the script is started as a non-root user, it re-executes itself with sudo -E.

Configuration

The runner is configured through environment variables. NPROCS is the only mandatory variable; the script exits with an error if it is not set. All other variables are optional and use the defaults shown below when omitted.

Mandatory Environment Variable

Variable	Description	Default
NPROCS	Number of MPI ranks to run on each host. The total rank count is NPROCS multiplied by the number of entries in HOSTS.	None

Optional Environment Variables

Variable	Description	Default
HOSTS	Comma-separated hosts for a multi-node run. Every host must have the same MASS client installation and permit passwordless root SSH.	localhost
DFS_PATH	Mounted MASS path used to look up the target pool and container. IOR accesses that target through DFS rather than writing through the mount.	/mnt/poc-home
BLOCK	IOR block size (-b): bytes written by each rank in each segment.	2g
XFER	IOR transfer size (-t): amount of data transferred by each I/O operation.	16m
SEGS	IOR segment count (-s) for each rank.	4
WR_ONLY	Set to 1 to run only the write phase and retain its test files for a later read-only run.	0
RD_ONLY	Set to 1 to read files retained by a matching write-only run. Do not enable it together with WR_ONLY.	0
SUMMARY	Machine-readable result as <path>,json or <path>,csv, for example /tmp/ior.json,json. On multi-node runs, the parent directory must exist on every host.	Unset
CONFIG	IOR script configuration file. Values in this file override BLOCK, XFER, SEGS, phase flags, and built-in test options. If the file is unreadable, the runner uses its built-in defaults.	config.ior next to the runner
DAOS_AGENT_DRPC_DIR	Directory containing daos_agent.sock. Set it only to override agent socket discovery.	/run/boostx-agent, or an active /tmp/boostx-agent-* directory

For example, the following runs a larger workload and writes a JSON summary:

NPROCS=32 BLOCK=4g XFER=32m SEGS=8 SUMMARY=/tmp/ior.json,json \
  /opt/boostx-sds/ior/scripts/ior.sh

Notes

• A read-only run must use files created by a write-only run with the same values for NPROCS, BLOCK, XFER, and SEGS.
• For a multi-node summary, its parent directory must exist on every host.
• For package layout and the rest of the client toolchain, see Developer Toolkit.