mirror of
https://github.com/AltraMayor/f3.git
synced 2025-08-03 18:46:00 -04:00
372 lines
12 KiB
ReStructuredText
372 lines
12 KiB
ReStructuredText
f3 - Fight Flash Fraud
|
|
======================
|
|
|
|
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 <#examples>`__
|
|
- `Installation <#installation>`__
|
|
- `Other resources <#other-resources>`__
|
|
|
|
.. _examples:
|
|
|
|
.. highlight:: bash
|
|
|
|
Examples
|
|
========
|
|
|
|
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/sdb
|
|
|
|
.. 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/sdb
|
|
|
|
Installation
|
|
============
|
|
|
|
Download and Compile
|
|
--------------------
|
|
|
|
The files of the stable version of F3 are
|
|
`here <https://github.com/AltraMayor/f3/releases>`__. The
|
|
following command uncompresses the files::
|
|
|
|
$ unzip f3-8.0.zip
|
|
|
|
|
|
Compile stable software on Linux or FreeBSD
|
|
-------------------------------------------
|
|
|
|
To build::
|
|
|
|
make
|
|
|
|
If you want to install f3write and f3read, run the following command::
|
|
|
|
make install
|
|
|
|
Compile stable software on Windows/Cygwin
|
|
-----------------------------------------
|
|
|
|
f3write and f3read can be installed on Windows, but currently f3probe, f3fix,
|
|
and f3brew `require Linux <#the-extra-applications-for-linux>`__. To use them
|
|
on a Windows machine, use the `Docker Installation <#docker>`__. 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::
|
|
|
|
make install
|
|
|
|
Compile stable software on Apple Mac
|
|
------------------------------------
|
|
|
|
f3write and f3read can be installed on Mac, but currently f3probe, f3fix, and
|
|
f3brew `require Linux <#the-extra-applications-for-linux>`__. To use them on
|
|
Mac, use the `Docker Installation <#docker>`__. For f3write and f3read, read
|
|
on.
|
|
|
|
Using HomeBrew
|
|
~~~~~~~~~~~~~~
|
|
|
|
If you have Homebrew already installed in your computer, the command
|
|
below will install F3::
|
|
|
|
brew install f3
|
|
|
|
Using MacPorts
|
|
~~~~~~~~~~~~~~
|
|
|
|
If you use MacPorts instead, use the following command::
|
|
|
|
port install f3
|
|
|
|
Compiling the latest development version from the source code
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
Most of the f3 source code builds fine using XCode, the only dependency
|
|
missing is the GNU C library "argp". You can build argp from scratch, or
|
|
use the version provided by HomeBrew and MacPorts as "argp-standalone"
|
|
|
|
The following steps have been tested on OS X El Capitan 10.11.
|
|
|
|
1) Install Apple command line tools::
|
|
|
|
xcode-select --install
|
|
|
|
See http://osxdaily.com/2014/02/12/install-command-line-tools-mac-os-x/
|
|
for details.
|
|
|
|
2) Install Homebrew or MacPorts
|
|
|
|
HomeBrew::
|
|
|
|
/usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
|
|
|
|
See https://brew.sh/ for details.
|
|
|
|
MacPorts: https://www.macports.org/install.php
|
|
|
|
3) Install argp library::
|
|
|
|
brew install argp-standalone
|
|
|
|
See http://brewformulas.org/ArgpStandalone and
|
|
https://www.freshports.org/devel/argp-standalone/ for more
|
|
information.
|
|
|
|
Or, for MacPorts::
|
|
|
|
port install argp-standalone
|
|
|
|
See https://trac.macports.org/browser/trunk/dports/sysutils/f3/Portfile
|
|
for more information.
|
|
|
|
4) Build F3::
|
|
|
|
When using Homebrew, you can just run::
|
|
|
|
make
|
|
|
|
When using MacPorts, you will need to pass the location where MacPorts
|
|
installed argp-standalone::
|
|
|
|
make ARGP=/opt/local
|
|
|
|
Docker
|
|
------
|
|
|
|
Quick Start
|
|
~~~~~~~~~~~
|
|
|
|
A pre-built `image <https://cloud.docker.com/repository/docker/peron/f3>`__
|
|
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/sdb::
|
|
|
|
docker run -it --rm --device /dev/sdb peron/f3 f3probe --destructive --time-ops /dev/sdb
|
|
|
|
Optionally, you can also build your own container *if* you don't want to use the
|
|
pre-built image. From this directory, run::
|
|
|
|
docker build -t f3:latest .
|
|
docker run -it --rm --device <device> f3:latest <f3-command> [<f3-options>] <device>
|
|
|
|
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]
|
|
<https://github.com/docker/for-mac/issues/3110#issuecomment-456853036>`__
|
|
`[stackexchange]
|
|
<https://devops.stackexchange.com/questions/4572/how-to-pass-a-dev-disk-device-on-macos-into-linux-docker/6076#6076>`__
|
|
`[tty]
|
|
<https://christopherjmcclellan.wordpress.com/2019/04/21/using-usb-with-docker-for-mac/#tldr>`__)
|
|
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 :code:`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
|
|
<https://mil.ad/docker/2018/05/06/access-usb-devices-in-container-in-mac.html>`__
|
|
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.
|
|
:code:`--vendorid` and :code:`--productid` can be found on Mac in "System
|
|
Information" under "USB". You can also try searching for the right device in
|
|
:code:`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, :code:`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/sdb peron/f3 f3probe --destructive --time-ops /dev/sdb
|
|
|
|
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/sdb peron/f3 bash
|
|
|
|
so that you can run commands like :code:`ls /dev/*`.
|
|
|
|
The extra applications for Linux
|
|
--------------------------------
|
|
|
|
Install dependencies
|
|
~~~~~~~~~~~~~~~~~~~~
|
|
|
|
f3probe and f3brew require version 1 of the library libudev, and f3fix
|
|
requires version 0 of the library libparted to compile. On Ubuntu, you
|
|
can install these libraries with the following command::
|
|
|
|
sudo apt-get install libudev1 libudev-dev libparted-dev
|
|
|
|
If you are running a version of Ubuntu before 20.04.1, replace the package `libparted-dev`
|
|
on the command line above with `libparted0-dev`.
|
|
|
|
On Fedora, you can install these libraries with the following command::
|
|
|
|
sudo dnf install systemd-devel parted-devel
|
|
|
|
Compile the extra applications
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
::
|
|
|
|
make extra
|
|
|
|
.. note::
|
|
- The extra applications are only compiled and tested on Linux
|
|
platform.
|
|
- Please do not e-mail me saying that you want the extra
|
|
applications to run on your platform; I already know that.
|
|
- If you want the extra applications to run on your platform, help
|
|
to port them, or find someone that can port them for you. If you
|
|
do port any of them, please send me a patch to help others.
|
|
- The extra applications are f3probe, f3brew, and f3fix.
|
|
|
|
If you want to install the extra applications, run the following
|
|
command::
|
|
|
|
make install-extra
|
|
|
|
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 <https://github.com/zwpwjwtz/f3-qt>`__ is a Linux GUI that uses
|
|
QT. F3 QT supports ``f3write``, ``f3read``, ``f3probe``, and ``f3fix``. Author:
|
|
Tianze.
|
|
|
|
`F3XSwift <https://github.com/vrunkel/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 <https://github.com/whitslack/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.
|