Skip to content

Commit d20a472

Browse files
midnight-wonderermidnight-wonderer
committed
docs: Edit README to improve clarity, and streamline usage and installation instructions.
1 parent 392e3ee commit d20a472

1 file changed

Lines changed: 104 additions & 110 deletions

File tree

‎README.md‎

Lines changed: 104 additions & 110 deletions
Original file line numberDiff line numberDiff line change
@@ -1,177 +1,171 @@
1-
# disktest - Tester for Solid State Disks (SSDs), Non-Volatile Memory Storage (NVMe), Hard Disks (HDDs), USB Sticks, SD-Cards, etc.
1+
# disktest - Storage Media Tester
22

3-
[Homepage](https://bues.ch/h/disktest)
3+
[Homepage](https://bues.ch/h/disktest) | [crates.io site](https://crates.io/crates/disktest) | [Github repository](https://github.com/mbuesch/disktest)
44

5-
[crates.io site](https://crates.io/crates/disktest)
5+
**Disktest** is a tool to check Solid State Disks (SSDs), Non-Volatile Memory Storage (NVMe), Hard Disks (HDDs), USB sticks, SD cards, or other storage media for errors.
66

7-
[Github repository](https://github.com/mbuesch/disktest)
8-
9-
Disktest is a tool to check Solid State Disks, Non-Volatile Memory Storage, Hard Disks, USB sticks, SD cards or other storage media for errors.
10-
11-
It does so by writing a pseudo-random sequence to the device and then reading it back and verifying it against the same pseudo-random sequence.
7+
## Why use disktest?
128

139
This tool can be used to:
1410

15-
- Check disks for hardware errors (e.g. platter errors, flash errors, etc.).
16-
- Overwrite storage media with a cryptographically-strong pseudo-random stream. This can either be used to delete existing data on the disk, or to prepare the disk for encryption.
17-
- Test for tampered media that pretend to have more storage area than they physically have. Sometimes such media are sold by fraudulent sellers at cheap prices.
18-
- Measure read and write speed.
19-
- ... probably lots of other tasks.
20-
21-
The pseudo-random number stream is generated by the following algorithm:
22-
23-
```
24-
OUTPUT_DATA := CHACHA20(PBKDF2(SEED | THREAD_ID | ROUND_ID))
25-
```
26-
27-
If more than one thread is used, then each thread generates such a stream, and the streams are interleaved in an alternating pattern.
11+
- **Detect Hardware Errors**: Check disks for platter errors, flash memory degradation, or other hardware failures.
12+
- **Secure Data Wipe**: Overwrite storage media with a cryptographically-strong pseudo-random stream. This is ideal for securely deleting existing data or preparing a disk for encryption.
13+
- **Uncover Fake Capacity Storage**: Test for tampered media that pretend to have more storage area than they physically possess (common with cheap, fraudulent SD cards or USB drives).
14+
- **Benchmark Performance**: Measure the raw read and write speed of your storage devices.
15+
- ... and lots of other storage-related tasks.
2816

17+
## Comparison with F3
2918

30-
# Security
19+
While tools like `f3` (Fight Flash Fraud) or `h2testw` are also used to test storage media, **disktest** is designed with several advantages:
20+
- **Generally Faster**: Disktest is typically much faster.
21+
- **Realistic Full-Disk Workload**: It ensures that every piece of data can be retrieved accurately after writing the disk to full capacity, mimicking heavy real-world usage.
22+
- **Unfakable Verification**: Because every single byte is part of an unpredictable pseudo-random sequence, disk controllers cannot cheat the test using transparent data compression or deduplication. Every byte must be physically stored and correctly retrieved.
3123

32-
The default algorithm [ChaCha20](https://en.wikipedia.org/wiki/Salsa20) is a cryptographically strong random number generator. That means if the seed is kept secret, the pseudo-random sequence cannot be predicted or reconstructed by anybody else.
24+
## Quick Start Example
3325

34-
See option `--seed` under `--help` for more details.
26+
*WARNING*: These commands will irrevocably overwrite all data on the target storage device! Be absolutely certain that the device path is correct before starting. Your data will not be recoverable.
3527

28+
### Linux
3629

37-
# Linux example
38-
39-
The following disktest invocation will write a secure sequence to the disk device `/dev/sdc` and subsequently read back and verify the sequence.
30+
Write a secure pseudo-random sequence to the disk and immediately verify it:
4031

4132
```sh
33+
# For a standard block device
4234
disktest --write --verify -j0 /dev/sdc
43-
```
4435

45-
For NVMe:
46-
47-
```sh
36+
# For an NVMe drive
4837
disktest --write --verify -j0 /dev/nvme0n1
49-
```
50-
51-
For SD / MMC:
5238

53-
```sh
39+
# For an SD / MMC card
5440
disktest --write --verify -j0 /dev/mmcblk0
5541
```
42+
*(Note: You usually need `root` permissions to write to raw disk devices).*
5643

57-
*WARNING*: This will irrevocably overwrite all data on the storage device! Be absolutely certain that the device path is correct before starting the command. Your data will not be recoverable.
58-
59-
You probably need `root` permissions to write to raw disk devices (`/dev/sdX`, `/dev/nvmeXn1` or `/dev/mmcblkX`).
44+
### Windows
6045

61-
The target `device` does not have to be an actual hardware device node. It can be any file path on any file system. For example you can mount an USB stick file system and write to a file on that file system. However, please note that this leaves a couple of minor untested spots in the USB stick's memory, which are reserved for the file system. Also see the `Windows` section below.
62-
63-
64-
# Windows example
65-
66-
On Windows disktest can write to any file on any mounted storage media or raw disks.
67-
68-
If your storage media under test is drive E, then the following command would write a test file on drive E and verify it:
46+
Write a test file to a mounted drive `E:` and verify it:
6947

7048
```cmd
7149
disktest --write --verify -j0 E:\testfile.img
7250
```
51+
*(See the [Detailed Usage](#detailed-usage) section for testing raw drives on Windows).*
7352

74-
But note that testing on the filesystem level, as shown above, does not test the full device.
75-
It will omit the disk areas that the filesystem uses internally.
76-
Therefore, you may want to write to the raw disk E using the Windows raw drive notation, as follows:
77-
78-
```cmd
79-
disktest --write --verify -j0 \\.\E:
80-
```
53+
---
8154

82-
or
55+
## Installation
8356

84-
```cmd
85-
disktest --write --verify -j0 \\.\PhysicalDrive2
57+
### From crates.io (Recommended)
58+
Download the latest version of disktest and install it to `$HOME/.cargo/bin`:
59+
```sh
60+
cargo install disktest
8661
```
8762

88-
Doing so will completely wipe all data (including the filesystem) on this disk.
89-
90-
Always make sure that you selected the correct drive.
91-
Especially in the `\\\\.\PhysicalDriveX` notation, it is extremely easy to overwrite the wrong drive by accident.
92-
Therefore, the `\\\\.\X:` (where X is the drive letter) notation is preferred.
93-
63+
### From Source
64+
Build and install from the source package:
65+
```sh
66+
cd path/to/source/package
67+
cargo install --path .
68+
```
69+
Or run in-place without installing:
70+
```sh
71+
cargo run --release -- DISKTEST_OPTIONS_HERE
72+
```
9473

95-
# Dependencies
74+
---
9675

97-
- [Rust 1.85.0](https://www.rust-lang.org/) or later.
98-
- Crate dependencies are automatically downloaded by Cargo.
76+
## Detailed Usage
9977

78+
The target `device` does not have to be an actual hardware device node. It can be any file path on any file system. However, testing on the filesystem level leaves minor spots untested (those reserved for the filesystem itself). To test the *entire* device, you must target the raw device.
10079

101-
# Installing from crates.io
80+
### Windows Raw Drives
81+
To test an entire drive on Windows, use the raw drive notation. The `\\.\X:` (where X is the drive letter) notation is preferred to avoid accidental overwrites:
10282

103-
Download the latest version of disktest from [crates.io](https://crates.io/) and install it to `$HOME/.cargo/bin`:
83+
```cmd
84+
disktest --write --verify -j0 \\.\E:
85+
```
86+
Alternatively:
87+
```cmd
88+
disktest --write --verify -j0 \\.\PhysicalDrive2
89+
```
10490

91+
### Command Line Options
92+
To see all available command-line options:
10593
```sh
106-
cargo install disktest
94+
disktest --help
95+
# or if running from source: cargo run --release -- --help
10796
```
10897

98+
### Power Cycle Tests
10999

110-
# Installing from source package
111-
112-
Build disktest and install it to `$HOME/.cargo/bin`:
100+
It is recommended to test a device's data retention capabilities in a powered-down state. You can achieve this by splitting the write and verify passes. Note that you **must** supply the same `--seed` for both runs, so `disktest` knows the exact pseudo-random sequence to expect during verification.
113101

102+
**1. Write the sequence:**
114103
```sh
115-
cd path/to/source/package
116-
cargo install --path .
104+
disktest --write --seed <YOUR_SEED> -j0 /dev/sdc
117105
```
118106

107+
**2. Safely remove and power down:**
108+
Safely unmount/eject the device, and physically unplug it.
119109

120-
# Running from source package without installing
121-
122-
Build and run disktest in place without installing it:
123-
110+
**3. Reconnect and verify:**
124111
```sh
125-
cd path/to/source/package
126-
cargo run --release -- DISKTEST_OPTIONS_HERE
112+
disktest --verify --seed <YOUR_SEED> -j0 /dev/sdc
127113
```
128114

129-
See below for a description of the available `disktest` options.
130-
115+
---
131116

132-
# Disktest command line options
117+
## Security & Algorithm
133118

134-
Please run either of the following commands to show more information about the available command-line options.
135-
136-
```sh
137-
cargo run --release -- --help
138-
disktest --help
119+
Disktest writes a pseudo-random sequence, reads it back, and verifies it. The stream is generated by:
120+
```
121+
OUTPUT_DATA := CHACHA20(PBKDF2(SEED | THREAD_ID | ROUND_ID))
139122
```
123+
If more than one thread is used, each thread generates a stream, and they are interleaved in an alternating pattern.
140124

125+
The default algorithm [ChaCha20](https://en.wikipedia.org/wiki/Salsa20) is a cryptographically strong random number generator. If the seed is kept secret, the sequence cannot be predicted or reconstructed by anybody else. See `--seed` in the `--help` output for more details.
141126

142-
# Speed
127+
---
143128

144-
The following table shows some example speed measurements of disktest in various operation modes on different hardware.
129+
## Speed Measurements
145130

146-
These speed tests don't write to an actual disk, but only to the `/dev/null` device, which is a device that does nothing. So these speed test results do not include the speed limits of any physical disk hardware.
131+
The following table shows example speed measurements using different algorithms and hardware.
147132

148-
| Command | Algorithm | Hardware | Data rate written |
149-
| ------------------------------------- | --------- | ------------------------------- | ----------------- |
150-
| disktest -j12 -ACHACHA20 -w /dev/null | ChaCha20 | AMD Ryzen 5 5500U; 6x2 cores | 8.4 GiB/s |
151-
| disktest -j12 -ACHACHA12 -w /dev/null | ChaCha12 | AMD Ryzen 5 5500U; 6x2 cores | 8.7 GiB/s |
152-
| disktest -j12 -ACHACHA8 -w /dev/null | ChaCha8 | AMD Ryzen 5 5500U; 6x2 cores | 8.7 GiB/s |
153-
| disktest -j12 -ACRC -w /dev/null | CRC | AMD Ryzen 5 5500U; 6x2 cores | 8.8 GiB/s |
154-
| disktest -j4 -ACHACHA20 -w /dev/null | ChaCha20 | Intel i5-3320M; 2x2 cores | 2.1 GiB/s |
155-
| disktest -j4 -ACHACHA12 -w /dev/null | ChaCha12 | Intel i5-3320M; 2x2 cores | 3.3 GiB/s |
156-
| disktest -j4 -ACHACHA8 -w /dev/null | ChaCha8 | Intel i5-3320M; 2x2 cores | 4.5 GiB/s |
157-
| disktest -j4 -ACRC -w /dev/null | CRC | Intel i5-3320M; 2x2 cores | 8.2 GiB/s |
158-
| disktest -j4 -ACHACHA20 -w /dev/null | ChaCha20 | Raspberry Pi 4; 4 cores 1.5 GHz | 455 MiB/s |
159-
| disktest -j4 -ACHACHA12 -w /dev/null | ChaCha12 | Raspberry Pi 4; 4 cores 1.5 GHz | 720 MiB/s |
160-
| disktest -j4 -ACHACHA8 -w /dev/null | ChaCha8 | Raspberry Pi 4; 4 cores 1.5 GHz | 990 MiB/s |
161-
| disktest -j4 -ACRC -w /dev/null | CRC | Raspberry Pi 4; 4 cores 1.5 GHz | 3.1 GiB/s |
133+
| Algorithm | Hardware | Threads (`-j`) | Data rate written |
134+
| --------- | ------------------------------- | -------------- | ----------------- |
135+
| ChaCha20 | AMD Ryzen 5 5500U; 6x2 cores | 12 | 8.4 GiB/s |
136+
| ChaCha12 | AMD Ryzen 5 5500U; 6x2 cores | 12 | 8.7 GiB/s |
137+
| ChaCha8 | AMD Ryzen 5 5500U; 6x2 cores | 12 | 8.7 GiB/s |
138+
| CRC | AMD Ryzen 5 5500U; 6x2 cores | 12 | 8.8 GiB/s |
139+
| ChaCha20 | Intel i5-3320M; 2x2 cores | 4 | 2.1 GiB/s |
140+
| ChaCha12 | Intel i5-3320M; 2x2 cores | 4 | 3.3 GiB/s |
141+
| ChaCha8 | Intel i5-3320M; 2x2 cores | 4 | 4.5 GiB/s |
142+
| CRC | Intel i5-3320M; 2x2 cores | 4 | 8.2 GiB/s |
143+
| ChaCha20 | Raspberry Pi 4; 4 cores 1.5 GHz | 4 | 455 MiB/s |
144+
| ChaCha12 | Raspberry Pi 4; 4 cores 1.5 GHz | 4 | 720 MiB/s |
145+
| ChaCha8 | Raspberry Pi 4; 4 cores 1.5 GHz | 4 | 990 MiB/s |
146+
| CRC | Raspberry Pi 4; 4 cores 1.5 GHz | 4 | 3.1 GiB/s |
162147

163-
The read data rates are similar because the algorithm used is exactly the same.
148+
To reproduce these metrics, use the following command format:
149+
```sh
150+
disktest -j<Threads> -A<ALGORITHM> -w /dev/null
151+
```
152+
153+
* Tests were performed writing to `/dev/null` to measure raw generation speed, independent of physical disk bottlenecks.
154+
* Read data rates are similar as the generation algorithm is identical.
164155

156+
---
165157

166-
# CPU native optimization
158+
## Build Notes & Dependencies
167159

168-
Note that the default [cargo configuration](.cargo/config.toml) supplied with this package sets the Rust compiler option `-Ctarget-cpu=native` to optimize for the best performance on your CPU.
160+
- Requires **[Rust 1.85.0](https://www.rust-lang.org/) or later**.
161+
- Crate dependencies are automatically downloaded by Cargo.
169162

170-
But this means that binaries compiled with this optimizations are non-portable to older CPUs.
171-
If you want portable binaries, then you probably want to remove this optimization option.
163+
### CPU Native Optimization
164+
The default [cargo configuration](.cargo/config.toml) supplied with this package sets the Rust compiler option `-Ctarget-cpu=native` to optimize for the best performance on your CPU. This means compiled binaries are non-portable to older CPUs. Remove this optimization option if you need portable binaries.
172165

166+
---
173167

174-
# License
168+
## License
175169

176170
Copyright (c) 2020-2026 Michael Büsch <m@bues.ch> and contributors
177171

0 commit comments

Comments
 (0)