f3 is a simple tool that tests flash cards capacity and performance to see if they live up to claimed specifications. It fills the device with pseudorandom data and then checks if it returns the same on reading.

F3 stands for Fight Flash Fraud, or Fight Fake Flash.

Table of Contents

Examples

We’ll use /dev/sdX as a placeholder here, you need to replace X with a lowercase letter so that it matches the device you want to use. lsblk will show you an overview of your current devices.

Testing performance with f3read/f3write

Use these two programs in this order. f3write will write large files to your mounted disk and f3read will check if the flash disk contains exactly the written files:

$ ./f3write /media/michel/5EBD-5C80/
$ ./f3read /media/michel/5EBD-5C80/

Please replace “/media/michel/5EBD-5C80/” with the appropriate path. USB devices are mounted in “/Volumes” on Macs.

If you have installed f3read and f3write, you can remove the “./” that is shown before their names.

Quick capacity tests with f3probe

f3probe is the fastest drive test and suitable for large disks because it only writes what’s necessary to test the drive. It operates directly on the (unmounted) block device and needs to be run as a privileged user:

# ./f3probe --destructive --time-ops /dev/sdX

Warning

This will destroy any previously stored data on your disk!

Correcting capacity to actual size with f3fix

f3fix creates a partition that fits the actual size of the fake drive. Use f3probe’s output to determine the parameters for f3fix:

# ./f3fix --last-sec=16477878 /dev/sdX

Installation

Download and Compile

The files of the stable version of F3 are here. The following command uncompresses the files:

Compile stable software on Linux or FreeBSD

To build:

If you want to install f3write and f3read, run the following command:

Compile stable software on Windows/Cygwin

f3write and f3read can be installed on Windows, but currently f3probe, f3fix, and f3brew require Linux. To use them on a Windows machine, use the Docker Installation. For f3write and f3read, read on.

If you haven’t already, install the following Cygwin packages and their dependencies:

  • gcc-core
  • make
  • libargp-devel

To build, you need special flags:

export LDFLAGS="$LDFLAGS -Wl,--stack,4000000 -largp"
make

If you want to install f3write and f3read, run the following command:

Compile stable software on Apple Mac

f3write and f3read can be installed on Mac, but currently f3probe, f3fix, and f3brew require Linux. To use them on Mac, use the Docker Installation. For f3write and f3read, read on.

Using HomeBrew

If you have Homebrew already installed in your computer, the command below will install F3:

Using MacPorts

If you use MacPorts instead, use the following command:

Docker

Quick Start

A pre-built image is available over at Docker Hub, ready to be used. With docker started, just run:

docker run -it --rm --device <device> peron/f3 <f3-command> [<f3-options>] <device>

For example, to probe a drive mounted at /dev/sdX:

docker run -it --rm --device /dev/sdX peron/f3 f3probe --destructive --time-ops /dev/sdX

Optionally, you can also build your own container if you don’t want to use the pre-built image. From this directory, run:

or:

docker build -t f3:latest .

To run f3 commands using your newly built Docker image:

docker run -it --rm --device <device> f3:latest <f3-command> [<f3-options>] <device>

docker run -it --rm --device /dev/sdX f3:latest f3probe --destructive --time-ops /dev/sdX
docker run -it --rm -v /path/to/mounted/device:/mnt/ f3:latest f3write /mnt/
docker run -it --rm -v /path/to/mounted/device:/mnt/ f3:latest f3read /mnt/

Drive Permissions / Passthrough

Getting the drive device to map into the Docker container is tricky for Mac and Windows. Passing through devices on Mac and Windows is a well-documented issue ([github] [stackexchange] [tty]) On Linux it should just work, but on Mac or Windows, Docker tends to map the drive as a normal directory rather than a mounted drive and you will get an error like f3probe: Can't open device '/opt/usb': Is a directory, that is if you can map it at all.

To solve this, we can use docker-machine to create a VirtualBox VM (boot2docker), in which to run the Docker container. Since VirtualBox can handle device pass-through, we can pass the device through to the VirtualBox VM which can then pass the device through to the Docker container. Milad Alizadeh wrote up some good instructions here which are geared towards USB devices, but it shouldn’t be too hard to adapt to other drive types. Here’s what I typed into my Mac terminal (probably similar for Windows, but untested):

docker-machine create -d virtualbox default
docker-machine stop
vboxmanage modifyvm default --usb on
docker-machine start
vboxmanage usbfilter add 0 --target default --name flashdrive --vendorid 0x0123 --productid 0x4567
eval $(docker-machine env default)

For the usbfilter add command, note that the “name” argument is the new name you’re giving the filter so you can name it whatever you want. --vendorid and --productid can be found on Mac in “System Information” under “USB”. You can also try searching for the right device in vboxmanage list usbhost.

Alternatively, you may opt to add the device through the VirtualBox GUI application instead:

docker-machine create -d virtualbox default
docker-machine stop
# open VirtualBox and manually add the drive device before proceeding to the next command
docker-machine start
eval $(docker-machine env default)

Once you’ve run the above commands, unplug and replug the flash drive and run:

docker-machine ssh default "lsblk"

to list the devices. Search for the correct drive - the “SIZE” column may be helpful in locating the device of interest. For example, sdb is a common mount point for a USB drive. Now you should be able to run the command from Quick Start:

docker run --rm -it --device /dev/sdX peron/f3 f3probe --destructive --time-ops /dev/sdX

You may find it useful to enter a bash prompt in the Docker container to poke around the filesystem:

docker run --rm -it --device /dev/sdX peron/f3 bash

so that you can run commands like ls /dev/*.

Other resources

Graphical User Interfaces

Thanks to our growing community of flash fraud fighters, we have the following graphical user interfaces (GUI) available for F3:

F3 QT is a Linux GUI that uses QT. F3 QT supports f3write, f3read, f3probe, and f3fix. Author: Tianze.

F3XSwift is a Mac GUI. F3XSwift supports f3write and f3read. Author: Volker Runkel.

Please support the above projects by testing them and giving feedback to their authors. This will improve their code as it has improved mine.

Files

changelog   - Change log for package maintainers
f3read.1    - Man page for f3read and f3write
            In order to read this manual page, run `man ./f3read.1`
            To install the page, run
            `install --owner=root --group=root --mode=644 f3read.1 /usr/share/man/man1`
LICENSE     - License (GPLv3)
Makefile    - make(1) file
README      - This file
*.h and *.c - C code of F3

Bash scripts

Although the simple scripts listed in this section are ready for use, they are really meant to help you to write your own scripts. So you can personalize F3 to your specific needs:

f3write.h2w - Script to create files exactly like H2testw.
    Use example: `f3write.h2w /media/michel/5EBD-5C80/`

log-f3wr    - Script that runs f3write and f3read, and records
              their output into a log file.
    Use example: `log-f3wr log-filename /media/michel/5EBD-5C80/`

Please notice that all scripts and use examples above assume that f3write, f3read, and the scripts are in the same folder.

Flakyflash

If your flash isn’t fraudulent (or you’ve run f3fix to “fix” it) but you’re still seeing some sporadic data corruption, then you may have “flaky flash.” If your flash is formatted using the FAT file system, then you can use Flakyflash to find the flaky data clusters and mark them as bad in the FAT. This may allow you to get a little more use out of your flash, but you should still consider it as failing and replace it ASAP.