Skip to content

Latest commit

 

History

History
127 lines (97 loc) · 5.73 KB

README.md

File metadata and controls

127 lines (97 loc) · 5.73 KB
Raw

what it is

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.

requirements

  • 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

compiling

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/.

using

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 tools

  • 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.

test methodology

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

build status

POSIX CI Windows CI Microcontrollers CI MacOS X CI

Coverity Codacy Badge

license

It is licensed under the MIT license. Written by Folkert van Heusden [email protected] in 2023/2024.