iESP is an iSCSI target that was originally designed for the ESP32 and Teensy 4.1 microcontroller. This allows you to boot your VMWare cluster from an SD-card :-) Since then it was ported to Linux, *BSD (tested on FreeBSD) and Microsoft Windows.
- a Linux/*BSD/Windows/Apple system with cmake and a C++ compiler
OR
- a supported microcontroller with an SD-card reader connected to it and platformio
For the ESP32/Teensy4.1:
- cd microcontrollers
- adjust the settings in data/cfg-iESP.json (see cfg-iESP.json.example)
- pio run -t upload -e ESP32-wemos # Wemos32 (WiFi)
- pio run -t upload -e ESP32-WT-ETH01 # WT32-ETH01 (Ethernet)
- pio run -t upload -e Teensy4_1 # Teensy4.1 (Ethernet)
For the Raspberry Pi Pico (RP2040W):
- cd microcontrollers/RP2040
-
- adjust the settings in "wifi.h"
- pio run
-
- Manually copy the .pio/build/BUILD_FOR_RP2040W/firmware.uf2 file onto the Pico
-
- Optionally connect a green LED to GPIO 17 and a yellow LED to GPIO 18
-
- Connect the following pins of your SD card reader to: MISO to GPIO 8, MOSI to GPIO 11, SCK to GPIO 10 and SS/CS to GPIO 12
For Linux/FreeBSD/Apple:
- mkdir build
- cd build
- cmake ..
- make
On Debian systems you can also run the following to create an installable .deb-package file:
- dpkg-buildpackage -us -uc
For RedHat (Fedora etc.):
- rpmbuild -ba iesp.spec
For Windows:
- mkdir buildMingw64 && cd buildMingw64
- cmake -DCMAKE_TOOLCHAIN_FILE=../mingw64.cmake ..
If you copy the result (iesp.exe) to an other windows system, make sure to include:
- libgcc_s_seh-1.dll
- libgomp-1.dll
- libstdc++-6.dll
- libwinpthread-1.dll
When crosscompiling under Debian, they are under /usr/lib/gcc/x86_64-w64-mingw32/13-posix/ and /usr/x86_64-w64-mingw32/lib/.
On the microcontroller it uses the connected SD-card. Make sure it is formatted in 'exfat' format (because of the file size). Create a test.dat file on the SD-card of the size you want your iSCSI target to be. The microcontroller version needs to be configured first: under microcontrollers/data there's a file called cfg-iESP.json.example. Rename this to cfg-iESP.json and enter e.g. appropriate WiFi settings (if applicable). Leave "syslog-host" empty to not send error logging to a syslog server.
On non-microcontrollers, run iESP with '-h' to see a list of switches. You probably want to set the backend file/device and to set the listen-address for example. You can also use an NBD-backend, making iESP in an iSCSI-NBD proxy.
This software has a custom SNMP library (SNMP agent).
- .1.3.6.1.2.1.142.1.10.2.1.1 - PDUs received
- .1.3.6.1.2.1.142.1.10.2.1.3 - number of bytes transmitted
- .1.3.6.1.2.1.142.1.10.2.1.4 - number of bytes received
- .1.3.6.1.2.1.142.1.1.1.1.10 - failure count
- .1.3.6.1.2.1.142.1.1.2.1.3 - PDUs with errors
- .1.3.6.1.2.1.142.1.6.2.1.1 - logins
- .1.3.6.1.2.1.142.1.6.3.1.1 - logouts
- .1.3.6.1.4.1.2021.100.2 - software version (not in Posix version)
- .1.3.6.1.4.1.2021.100.3 - build date
- .1.3.6.1.4.1.2021.11.54 - I/O wait in 100ths of a second
- .1.3.6.1.4.1.2021.11.9.0 - CPU usage
- .1.3.6.1.4.1.2021.13.15.1.1.2 - device name
- .1.3.6.1.4.1.2021.13.15.1.1.3 - number of bytes read
- .1.3.6.1.4.1.2021.13.15.1.1.4 - number of bytes written
- .1.3.6.1.4.1.2021.13.15.1.1.5 - number of reads
- .1.3.6.1.4.1.2021.13.15.1.1.6 - number of writes
- .1.3.6.1.4.1.2021.4.11.0 - free RAM (kB heap space, only on microcontrollers)
- .1.3.6.1.4.1.2021.9.1.9.1 - disk free estimate (will only work when using TRIM/UNMAP/DISCARD)
- test-blockdevice.py tests if what is written, is readable later on. this test overwrites the contents of a device!
- block-speed-randread.py measures the bandwidth/iops for random reads. use plot.sh to create png-files of the output.
Tested with "test-blockdevice.py", 'FSX' by Apple (using the rust version from https://github.com/asomers/fsx-rs the original version is at https://github.com/apple/fstools/ ) and the 'test-tool' from libiscsi.
For FSX:
- a disk-image is created on a ramdisk
- that disk-image is given as a backend to iesp
- in a virtual machine, a multipath setup (2 paths) is created
- in the virtual machine, the resulting iSCSI target is mounted under a mountpoint (ext4 filesystem with journal and discard-mountoption)
- 2 instances of FSX(-rs) are started and monitored for error messages
- 1 instance of test-blockdevice.py with 3 threads is started with trim/discard/unmap and deduplication-support set to 81% and trim to 9%
For test-blockdevice.py:
- a disk-image is created on a ramdisk
- that disk-image is given as a backend to iesp
- test-blockdevice.py is ran as: ./test-blockdevice.py -d -b 4096 -u 75 -n 6 -T 10
- any errors? then failed
- for a microcontroller: make sure block-count (-m) multiplied by block size (-b) is 8192 bytes or less as that's the limit in there
It is licensed under the MIT license. Written by Folkert van Heusden [email protected] in 2023/2024.
