update

docs/msd.md

@@ -5,6 +5,9 @@ It allows PiKVM to emulate a virtual CD-ROM or Flash Drive for the target host
 which will be available even in BIOS/UEFI when you need live disk to revive the OS
 or even reinstall it.
 
+!!! warning "Legacy note"
+    This document is relevant for `KVMD >= 3.249`. If you are using an older version, please update the PiKVM OS.
+
 | Take a look at the `Drive` menu in the Web UI |
 |-----------------------------------------------|
 | <img src="drive_menu.png" width="400" /> |
@@ -17,6 +20,14 @@ The following actions are available here:
 * Downloading an image from the PiKVM storage.
 * Drive connection management and much more.
 
+!!! warning
+    Never turn off the power of the PiKVM while the image is being uploaded
+    or while the image is connected to the target host in write mode.
+    This may cause file corruption.
+
+    The rest of the time, power off is safe because the PiKVM filesystem
+    will be in read-only mode.
+
 !!! info "The max CD-ROM image size is 2.2 GB"
     This is a Linux kernel [limitation](https://github.com/pikvm/pikvm/issues/322) on PiKVM,
     which currently cannot emulate a DVD drive.
@@ -31,9 +42,6 @@ The following actions are available here:
     The switch affects the settings of the future connection. For non-V3/V4 devices,
     you need to either reboot your target host or otherwise reinitialize the drive.
 
-!!! warning "Legacy note"
-    This document is relevant for `KVMD >= 3.249`. If you are using an older version, please update the PiKVM OS.
-
 
 -----
 ## Image uploading without Web UI
@@ -64,6 +72,73 @@ This protects the data from damage in the event of a sudden loss of power.
     An HTTP API for Mass Storage management is also [available](api.md#mass-storage-drive) for advanced use.
 
 
+-----
+## Writable Flash Drive
+
+When emulating Flash Drive on PiKVM, you can allow the target host to write files to the image.
+After stopping the drive, this image can be downloaded and opened on the local host.
+This is useful if you need to get some files from the target host.
+
+The file system image for the virtual Flash Drive must be prepared in advance.
+This can be done either on the local host or in the PiKVM console.
+
+Here some options:
+
+??? example "Step by step: Creating simple FAT32 image on PiKVM"
+
+    1. Remount internal storage to read-write mode manually:
+
+        ```
+        [root@pikvm ~]# kvmd-helper-otgmsd-remount rw
+        ```
+
+    2. Create an empty image file in `/var/lib/kvmd/msd` (this is the internal storage of PiKVM images)
+       of desired size (512MB in this example) and format it to FAT32:
+
+        ```
+        [root@pikvm ~]# dd if=/dev/zero of=/var/lib/kvmd/flash.img bs=1M count=512 status=progress
+        [root@pikvm ~]# loop=$(losetup -f)
+        [root@pikvm ~]# echo -e 'o\nn\np\n1\n\n\nt\nc\nw\n' | fdisk /var/lib/kvmd/flash.img
+        [root@pikvm ~]# losetup -P $loop /var/lib/kvmd/flash.img
+        [root@pikvm ~]# mkfs.vfat ${loop}p1
+        [root@pikvm ~]# losetup -d $loop
+        ```
+
+    3. Remount internal storage back to safe read-only mode:
+
+        ```
+        [root@pikvm ~]# kvmd-helper-otgmsd-remount ro
+        ```
+
+??? example "Step by step: Creating DMG image for target macOS on a local macOS"
+
+    1. Open `Disk Utility`.
+
+    2. Click menu `File -> New Image -> Blank Image`.
+
+    3. Set some options:
+
+        | `Format` and `Partitions` are very important |
+        |----------------------------------------------|
+        | <img src="macos_flash_dmg.png" width="400"> |
+
+    4. Click `Save`. The drive will automatically be mounted.
+
+    5. Copy files (such as BIOS updates) onto the new image (via terminal or drag and drop in Finder).
+
+    6. Eject image.
+
+    7. Rename the image file from `.dmg` to `.img`.
+
+    8. Upload the image to PiKVM.
+
+The image `flash.img` now should be available in the `Drive` menu in Web UI.
+Change drive mode to the `Flash` position and enable `Writable` switch.
+Connect the image, do whatever is necessary, with files, and disconnect it.
+The modified image containing your files can be downloaded to a local host
+by selecting it from the menu and clicking the floppy disk icon.
+
+
 -----
 ## NFS storage
 
@@ -162,7 +237,7 @@ So, to add a second virtual drive, follow this:
 
 
 -----
-## Second writable flash drive
+## Manual drives management
 
 The `kvmd-otgmsd` console utility is used to manage additional (and the first main one) drives.
 The full list of options can be found by running `kvmd-otgmsd --help`.
@@ -187,11 +262,12 @@ The full list of options can be found by running `kvmd-otgmsd --help`.
         [root@pikvm ~]# kvmd-otgmsd -i 1 --set-rw=1 --set-cdrom=0 --set-image=/root/flash.img
         ```
 
-    4. On this step, you will be able to access the flash drive from the target host.
-
         !!! note
             Index `0` represents the main drive that is controlled via the Web UI and API.
 
+    4. On this step, you will be able to access the flash drive from the target host
+        and format the it in the usual way.
+
     5. View the drive state:
 
         ```
@@ -333,23 +409,6 @@ Boot the server and select boot device like you normally would.
 E.g. in a AMI BIOS the boot device is called "Linux File-CD Gadget 0504".
 
 
------
-## Create a drive image on macOS
-
-1. Open Disk Utility.
-2. `File > New Image > Blank Image`.
-3. Save As: `pikvm-image.dmg`. Name: `pikvm-image`. Size: 100 MB (or whatever size you want). Format: `MS-DOS (FAT)`. Partitions: `Single partition - GUID Partition Map`. Image Format: `read/write disk image`.
-4. Click Save.
-5. The drive will automatically be mounted.
-6. Copy files (such as BIOS updates) onto the new image (via terminal or drag and drop in Finder).
-7. Eject image.
-8. Rename file to .img
-9. Upload image to PiKVM interface under "Drive".
-10. Select Drive Mode: `Flash` and then `Connect drive to Server`.
-
-You should be able to then mount it locally on the server, or reboot the device to do things like BIOS updates.
-
-
 -----
 ## An alternative to making a Windows boot image that does not require a physical usb flash drive