.\" Man page generated from reStructuredText.
.
.
.nr rst2man-indent-level 0
.
.de1 rstReportMargin
\\$1 \\n[an-margin]
level \\n[rst2man-indent-level]
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
-
\\n[rst2man-indent0]
\\n[rst2man-indent1]
\\n[rst2man-indent2]
..
.de1 INDENT
.\" .rstReportMargin pre:
. RS \\$1
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
. nr rst2man-indent-level +1
.\" .rstReportMargin post:
..
.de UNINDENT
. RE
.\" indent \\n[an-margin]
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.TH "STRESSANT" "1" "Feb 09, 2023" "???" "Stressant"
.SH NAME
stressant \- Stressant Documentation
.SH SYNOPSIS
.sp
\fBstressant\fP [\-h] [–version] [–log [PATH]] [–email EMAIL] [–smtpserver HOST] [–smtpuser USERNAME] [–smtppass PASSWORD] [–no\-information] [–no\-disk] [–smart] [–diskDevice PATH] [–jobFile PATH] [–overwrite] [–writeSize SIZE] [–directory PATH] [–diskRuntime DISKRUNTIME] [–no\-cpu] [–cpuBurnTime TIME] [–no\-network] [–iperfServer HOST] [–iperfTime TIME]
.SH DESCRIPTION
.sp
Stressant is a simple yet complete stress\-testing tool that forces a computer
to perform a series of test using well\-known Linux software in order to detect
possible design or construction failures.
.SH OPTIONS
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.TP
.B  \-h\fP,\fB  \-\-help
show this help message and exit
.TP
.B  \-\-version
show program’s version number and exit
.TP
.BI \-\-logfile \ <PATH>
write reports to the given logfile (default: stressant\-$HOSTNAME.log)
.TP
.BI \-\-email \ EMAIL
send report by email to given address
.TP
.BI \-\-smtpserver \ HOST
SMTP server to use, use a colon to specify the port
number if non\-default (25). willl attempt to use
STARTTLS to secure the connexion and fail if
unsupported (default: deliver using the –mta command)
.TP
.BI \-\-smtpuser \ USERNAME
username for the SMTP server (default: no user)
.TP
.BI \-\-smtppass \ PASSWORD
password for the SMTP server (default: prompted, if
–smtpuser is specified)
.TP
.B  \-\-no\-information\fP,\fB  \-\-information
gather basic information (default: True)
.TP
.B  \-\-no\-disk\fP,\fB  \-\-disk
run disk tests (default: True)
.TP
.B  \-\-smart\fP,\fB  \-\-no\-smart
run SMART tests (default: False)
.TP
.BI \-\-diskDevice \ PATH
device to benchmark (default: /dev/sda)
.TP
.BI \-\-jobFile \ PATH
path to the fio job file to use (default:
/usr/share/doc/fio/examples/basic\-verify.fio)
.TP
.B  \-\-overwrite
actually destroy the given device (default: False)
.TP
.BI \-\-writeSize \ SIZE
size to write to disk, bytes or percentage (default:
100M)
.TP
.BI \-\-directory \ PATH
directory to perform file tests in, created if missing
(default: None)
.TP
.BI \-\-diskRuntime \ DISKRUNTIME
upper limit for disk benchmark (default: 1m)
.TP
.B  \-\-no\-cpu\fP,\fB  \-\-cpu
run CPU tests (default: True)
.TP
.BI \-\-cpuBurnTime \ TIME
timeout for CPU burn\-in (default: 1m)
.TP
.B  \-\-no\-network\fP,\fB  \-\-network
run network tests (default: True)
.TP
.BI \-\-iperfServer \ HOST
iperf server to use (default: iperf.he.net)
.TP
.BI \-\-iperfTime \ TIME
timeout for iperf test, in seconds (default: 60)
.UNINDENT
.UNINDENT
.UNINDENT
.SH EXAMPLES
.sp
Small run load with defaults:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
stressant
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Very fast test, useful to run if you are worried about crashing the
machine:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
stressant \-\-writeSize 1M \-\-cpuBurnTime 1s \-\-iperfTime 1
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Extensive test with complete disk wipe and SMART long test:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
sudo stressant \-\-writeSize 100% \-\-overwrite \-\-cpuBurnTime 24h \-\-smart
# wait for the prescribed time, then show the SMART test results:
sudo smartctl \-l selftest
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Network test only on dedicated server:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
stressant \-\-no\-information \-\-no\-cpu \-\-no\-disk \-\-iperfServer iperf.example.net
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Send test results by email:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
stressant \-\-email person@example.com
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
If the mail server refuses mail from your location, you can use
another relay (password will be prompted):
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
stressant \-\-email person@example.com \-\-smtpserver submission.example.net \-\-smtpuser person \-\-smtppassword
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The \fBstressant\-meta\fP package also depends on other tools that are not
directly called by the automated script above, but are documented
below. The meta\-package also suggests many more useful tools.
.SS Wiping disks
.sp
\fBDANGER:\fP
.INDENT 0.0
.INDENT 3.5
Wiping disks, just in case it’s not totally obvious, will
\fBDELETE DATA\fP on the given file or device. \fBDO NOT\fP
run \fIANY\fP command in this section unless you are sure you
are writing to the \fBCORRECT DEVICE\fP and that you
\fBREALLY\fP want to \fBDESTROY DATA\fP\&.
.UNINDENT
.UNINDENT
.sp
As mentioned above, the \fBstressant\fP commandline tool can be used to
directly wipe a disk with the \fBfio(1)\fP command which is
actually a disk\-testing command that is abused for that purpose. You
may not have \fBfio(1)\fP installed on your machine, however, so
you may also use the venerable \fBbadblocks(8)\fP command to test
disks, without wiping them:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
badblocks \-nsv /dev/sdc
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
You can also wipe disks with the \fB\-w\fP flag:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
badblocks \-wsv /dev/sdc
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Be aware, however, that the effect of this will vary according to the
physical medium. For example, data may be recovered old spinning hard
drives (HDD) if only the above technique is used. For that purpose,
you should use a tool like \fBnwipe(1)\fP that erases disks using
multiple passes and patterns:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
nwipe \-\-autonuke \-\-nogui \-\-method=random \-\-verify=off \-\-logfile=nwipe.log /dev/sdc
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Those tools are also ineffective on solid state drives (SSD) as they
have a more complex logic layer and different layout semantics. For
this, you need to use a “ATA secure erase” procedure using the
\fBhdparm(8)\fP command:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
hdparm \-\-user\-master u \-\-security\-set\-pass Eins /dev/sdc
time hdparm \-\-user\-master u \-\-security\-erase Eins /dev/sdc
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
More information about this procedure is available in the \fI\%ATA wiki\fP\&.
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
The “secure erase” procedure basically delegates the task of
erasing the data to the disk controler. Nothing garantees
the destruction of that data, short of physical destruction
of the drive. See \fI\%this discussion\fP
for more information.
.UNINDENT
.UNINDENT
.SS Benchmarking disks
.sp
A good way to test disks is to wipe them, as above, but that’s
obviously destructive. Sometimes you might want to just test the
disk’s performance by hand, without wiping anything. Stressant ships
with \fBfio(1)\fP and \fBbonnie++(1)\fP for that
purpose. The latter is probably the simplest to use:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
bonnie++ \-s 4G \-d /mnt/disk/ \-n 1024
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Make sure the file size (\fB\-s\fP) is at least twice the main memory (see
\fBfree \-h\fP). The \fB/mnt/disk\fP directory should be writable by the
current user as well.
.sp
Stressant itself, when disk tests are enabled, will run the following
commands:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
dd bs=1M count=512 conv=fdatasync if=/dev/zero of=/mnt/disk/testfile
dd bs=1M count=512 conv=fdatasync if=/mnt/disk/testfile of=/dev/null
hdparm \-Tt /dev/disk
smartctl \-t long /dev/disk
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Those provide a quick overview of basic disk statistics as well.
.sp
More elaborate workloads can be done with \fBfio\fP\&. A simple benchmark
could be:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
fio \-\-name=stressant \-\-group_reporting \-\-directory=/mnt/disk \-\-size=100M
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
That is a basic read test. The result here, on a \fIWestern Digital Blue
M.2 500GB Internal SSD (WDS500G1B0B)\fP with LUKS encryption, LVM and
ext4, looks like:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
Run status group 0 (all jobs):
   READ: bw=267MiB/s (280MB/s), 267MiB/s\-267MiB/s (280MB/s\-280MB/s), io=100MiB (105MB), run=374\-374msec

Disk stats (read/write):
    dm\-3: ios=323/0, merge=0/0, ticks=484/0, in_queue=484, util=70.99%, aggrios=511/0, aggrmerge=0/0, aggrticks=764/0, aggrin_queue=764, aggrutil=76.86%
    dm\-0: ios=511/0, merge=0/0, ticks=764/0, in_queue=764, util=76.86%, aggrios=511/0, aggrmerge=0/0, aggrticks=547/0, aggrin_queue=576, aggrutil=73.55%
  sdb: ios=511/0, merge=0/0, ticks=547/0, in_queue=576, util=73.55%
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
A more realistic workload will ignore the cache (\fB\-\-direct=1\fP),
include random (\fB\-\-readwrite=randrw\fP) or sequential writes
(\fB\-\-readwrite=readwrite\fP), and parallelize the test to put more
pressure on the disk (\fB\-\-numjobs=4\fP):
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ fio \-\-name=stressant \-\-group_reporting \-\-directory=test \-\-size=100M \-\-readwrite=randrw \-\-direct=1 \-\-numjobs=4
Run status group 0 (all jobs):
   READ: bw=45.8MiB/s (48.0MB/s), 45.8MiB/s\-45.8MiB/s (48.0MB/s\-48.0MB/s), io=199MiB (209MB), run=4346\-4346msec
  WRITE: bw=46.2MiB/s (48.5MB/s), 46.2MiB/s\-46.2MiB/s (48.5MB/s\-48.5MB/s), io=201MiB (211MB), run=4346\-4346msec

Disk stats (read/write):
    dm\-3: ios=49674/50087, merge=0/0, ticks=10028/3912, in_queue=13972, util=97.22%, aggrios=50982/51423, aggrmerge=0/0, aggrticks=10204/3852, aggrin_queue=14092, aggrutil=96.62%
    dm\-0: ios=50982/51423, merge=0/0, ticks=10204/3852, in_queue=14092, util=96.62%, aggrios=50982/51423, aggrmerge=0/0, aggrticks=9042/2598, aggrin_queue=11224, aggrutil=92.54%
  sdb: ios=50982/51423, merge=0/0, ticks=9042/2598, in_queue=11224, util=92.54%
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
There is, of course, way more information shown by the default fio
output, including latency distribution, but those are the numbers
people first look for.
.sp
Parameters can be stored in a job file, passed as an argument to
fio. Examples are available in \fB/usr/share/doc/fio/examples\fP\&.
.sp
Stressant itself actually runs the equivalent of this:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
fio \-\-name=stressant \-\-group_reporting \-\-runtime=1m <(sed /^filename=/d /usr/share/doc/fio/examples/basic\-verify.fio ; echo size=100m) \-\-filename=test
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
There are many other ways to test disks, obviously. In
particular, simple tools like \fI\%disk\-filltest\fP might be
considered for inclusion in the future, provided they \fI\%enter
Debian\fP\&.
.UNINDENT
.UNINDENT
.SS Testing disks
.sp
The above actually tests disks in the sense that it looks at its
performance, but it’s more a benchmark than a “test”. For tests,
stressant will do a \fBsmartctl\fP run if the \fB\-\-smart\fP argument is
provided. What it actually does is:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
smartctl \-t long /dev/sdX
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Then \fBsmartctl \-l selftest /dev/sdX\fP can be used to track progress.
.sp
But this doesn’t work for all drives. For example, it may fail for
external USB enclosures.
.sp
smartmontools’s \fI\%NVMe support\fP is particularly
limited. \fI\%nvme\-cli\fP might be
able to deal with those drives better. In \fItheory\fP, it should support
running tests with:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
nvme device\-self\-test /dev/nvme0
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
But in practice, that often fails because the devices sometimes do not
support self\-test at all. You can look at the \fBsmart\-log\fP instead:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
nvme smart\-log /dev/nvme0
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
If the \fBnum_err_log_entries\fP entry is non\-zero, you can look at the
actual log:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
nvme error\-log /dev/nvme0
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
The above doesn’t detail how to interpret the output of
those commands, and probably should. Sorry.
.UNINDENT
.UNINDENT
.SS Testing flash memory
.sp
Flash memory cards are known to sometimes be “fake”, that is, they
misreport the actual capacity of the card or the bandwith
available. The stressant distribution therefore recommends a tool
called \fI\%f3\fP which allows you to
perform tests on the memory card. For example, this is a probe on a
honest memory card:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ sudo f3probe \-\-destructive \-\-time\-ops /dev/sdb
F3 probe 6.0
Copyright (C) 2010 Digirati Internet LTDA.
This is free software; see the source for copying conditions.

WARNING: Probing normally takes from a few seconds to 15 minutes, but
         it can take longer. Please be patient.

Good news: The device \(ga/dev/sdb\(aq is the real thing

Device geometry:
             *Usable* size: 30.00 GB (62916608 blocks)
            Announced size: 30.00 GB (62916608 blocks)
                    Module: 32.00 GB (2^35 Bytes)
    Approximate cache size: 0.00 Byte (0 blocks), need\-reset=no
       Physical block size: 512.00 Byte (2^9 Bytes)

Probe time: 4\(aq57\(dq
 Operation: total time / count = avg time
      Read: 3.07s / 4815 = 637us
     Write: 4\(aq51\(dq / 4192321 = 69us
     Reset: 324.5ms / 1 = 324.5ms
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fBWARNING:\fP
.INDENT 0.0
.INDENT 3.5
As the \fB\-\-destructive\fP flag hints, this will \fIdestroy\fP
the data on the card, so backup the data elsewhere before
doing those tests.
.UNINDENT
.UNINDENT
.sp
Note that older versions of \fBf3probe(1)\fP (6.0 or earlier)
will have trouble doing its job unless the card is connected through a
USB reader. Newer versions can deal with normal block devices,
provided that you pass the magic \fB\-\-reset\-type=2\fP argument. Here’s
such an example, on a fake MicroSD card that is labeled and announced
as 32GB but is actually closer to 16GB:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
root@curie:/home/anarcat/backup# ~anarcat/dist/f3/f3probe \-\-destructive \-\-time\-ops \-\-reset\-type=2  /dev/mmcblk0
F3 probe 6.0
Copyright (C) 2010 Digirati Internet LTDA.
This is free software; see the source for copying conditions.

WARNING: Probing normally takes from a few seconds to 15 minutes, but
         it can take longer. Please be patient.

Bad news: The device \(ga/dev/mmcblk0\(aq is a counterfeit of type limbo

You can \(dqfix\(dq this device using the following command:
f3fix \-\-last\-sec=30983327 /dev/mmcblk0

Device geometry:
             *Usable* size: 14.77 GB (30983328 blocks)
            Announced size: 31.25 GB (65536000 blocks)
                    Module: 32.00 GB (2^35 Bytes)
    Approximate cache size: 7.00 MB (14336 blocks), need\-reset=no
       Physical block size: 512.00 Byte (2^9 Bytes)

Probe time: 2\(aq29\(dq
 Operation: total time / count = avg time
      Read: 1.57s / 32937 = 47us
     Write: 2\(aq27\(dq / 200814 = 736us
     Reset: 2us / 2 = 1us
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
To repair the device, you can repartition it quickly with the
\fBf3fix(1)\fP command, as recommended in the output:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
f3fix \-\-last\-sec=30983327 /dev/mmcblk0
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
You will also need to reformat the partition so the new size is taken
into account, for example if this is a FAT32 filesystem:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
mkfs.fat /dev/mmcblk0p1
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
You can also perform bandwidth tests with \fBf3read(1)\fP and
\fBf3write(1)\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
pmount /dev/sdb1
f3write /media/sdb1
f3read /media/sdb1
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
This allows you to detect hidden caches and fake sizes directly as
well.
.SS Network performance testing
.sp
The \fB\-\-iperfServer\fP option of stressant runs a bandwidth test
against a predefined (or specified) server. You can, of course, call
\fI\%iPerf\fP directly to run your
own client/server tests to find issues in specific routes on the
network. The \fBiperf3\fP package was chosen over the older \fBiperf\fP
because public servers are available for the test to work
automatically. \fBiperf3\fP also has interesting performance features
like \fB\-\-zerocopy\fP and \fB\-\-file\fP, see \fBiperf3(1)\fP for
details.
.sp
To run a test, start a server:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
iperf3 \-\-server
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
On another machine, connect to the server:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
iperf3 \-\-client 192.0.2.1
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
This runs a TCP test. You can specify UDP test on the client and
disable bandwidth limitations (otherwise UDP tests are limited to 1
Mbit/s):
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
iperf3 \-c 192.0.2.1 \-\-udp \-\-bandwidth 0
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
To simulate a DDOS condition, you can try multiple clients and run the
test for a longer period:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
iperf3 \-c 192.0.2.1 \-u \-b 0 \-\-parallel 50 \-\-time 30
.ft P
.fi
.UNINDENT
.UNINDENT
.SH SEE ALSO
.sp
\fBhdparm(8)\fP, \fBsmartctl(8)\fP, \fBdd(1)\fP,
\fBfio()\fP, \fBstress\-ng(1)\fP, \fBiperf3(1)\fP
.SH AUTHOR
Antoine Beaupre
.SH COPYRIGHT
2023, Antoine Beaupre
.\" Generated by docutils manpage writer.
.