Share a Windows folder with Azure IoT Edge for Linux on Windows

Article
03/27/2024

Applies to: IoT Edge 1.4

Important

IoT Edge 1.4 is the supported release. If you are on an earlier release, see Update IoT Edge.

The Azure IoT Edge for Linux on Windows (EFLOW) virtual machine is isolated from the Windows host OS and the virtual machine doesn't have access to the host file system. By default, the EFLOW virtual machine has its own file system and has no access to the folders or files on the host computer. The EFLOW file and folder sharing mechanism provides a way to share Windows files and folders to the CBL-Mariner Linux EFLOW VM.

This article shows you how to enable the folder sharing between the Windows host OS and the EFLOW virtual machine.

Prerequisites

Azure IoT Edge for Linux on Windows 1.4.4 LTS update or higher. For more information about EFLOW release notes, see EFLOW Releases.
A machine with an x64/x86 processor.
Windows 10/11 (21H2) or higher with November 2022 update applied.

If you don't have an EFLOW device ready, you should create one before continuing with this guide. Follow the steps in Create and provision an IoT Edge for Linux on Windows device using symmetric keys to install, deploy and provision EFLOW.

How it works?

The Azure IoT Edge for Linux on Windows file and folder sharing mechanism is implemented using virtiofs technology. Virtiofs is a shared file system that lets virtual machines access a directory tree on the host OS. Unlike other approaches, it's designed to offer local file system semantics and performance. Virtiofs isn't a network file system repurposed for virtualization. It's designed to take advantage of the locality of virtual machines and the hypervisor. It takes advantage of the virtual machine's co-location with the hypervisor to avoid overhead associated with network file systems.

Only Windows folders can be shared to the EFLOW Linux VM and not the other way. Also, for security reasons, when setting the folder sharing mechanism, the user must provide a root folder and all the shared folders must be under that root folder.

Before starting with the adding and removing share mechanisms, let's define four concepts:

Root folder: Windows folder that is the root path containing subfolders to be shared to the EFLOW VM. The root folder isn't shared to the EFLOW VM. Only the subfolders under the root folder are shared to the EFLOW VM.
Shared folder: A Windows folder that's under the root folder and is shared with the EFLOW VM. All the content inside this folder is shared with the EFLOW VM.
Mounting point: Path inside the EFLOW VM where the Windows folder content is placed.
Mounting option: Read-only or read and write access. Controls the file access of the mounted folder inside the EFLOW VM.

Add shared folders

The following steps provide example EFLOW PowerShell commands to share one or more Windows host OS folders with the EFLOW virtual machine.

Note

If you're using Windows 10, ensure to reboot your Windows host OS after your fresh MSI instlalation or update before adding the Windows shared folders to the EFLOW VM.

Start by creating a new root shared folder. Go to File Explorer and choose a location for the root folder and create the folder.

For example, create a root folder under C:\Shared named EFLOW-Shared.
Create one or more shared folders to be shared with the EFLOW virtual machine. Shared folders should be created under the root folder from the previous step.

For example, create two folders one named Read-Access and one named Read-Write-Access.
Within the Read-Access shared folder, create a sample file that we'll later read inside the EFLOW virtual machine.

For example, using a text editor, create a file named Hello-World.txt within the Read-Access folder and save some text in the file.
Using a text editor, create the shared folder configuration file. This file contains the information about the folders to be shared with the EFLOW VM including the mounting points and the mounting options. For more information about the JSON configuration file, see PowerShell functions for IoT Edge for Linux on Windows.

For example, using the previous scenario, we'll share the two shared folders we created under the root folder.
- Read-Access shared folder will be mounted in the EFLOW virtual machine under the path /tmp/host-read-access with read-only access.
- Read-Write-Access shared folder will be mounted in the EFLOW virtual machine under the path /tmp/host-read-write-access with read and write access.
Create the JSON configuration file named sharedFolders.json within the root folder EFLOW-Shared with the following contents:
```
[
    {
        "sharedFolderRoot": "C:\\Shared\\EFLOW-Shared",
        "sharedFolders": [
            {   
                "hostFolderPath": "Read-Access", 
                "readOnly": true, 
                "targetFolderOnGuest": "/tmp/host-read-access" 
            },
            {   
                "hostFolderPath": "Read-Write-Access", 
                "readOnly": false, 
                "targetFolderOnGuest": "/tmp/host-read-write-access" 
            }
        ]
    }
]
```
Open an elevated PowerShell session by starting with Run as Administrator.
Create the shared folder assignation using the configuration file (sharedFolders.json) previously created.
```
Add-EflowVmSharedFolder -sharedFoldersJsonPath "C:\Shared\EFLOW-Shared\sharedFolders.json"
```
Once the cmdlet finished, the EFLOW virtual machine should have access to the shared folders. Connect to the EFLOW virtual machine and check the folders are correctly shared.
```
Connect-EflowVm
```
Go to the Read-Access shared folder (mounted under /tmp/host-read-access) and check the content of the Hello-World.txt file.

Note

By default, all shared folders are shared under root ownership. To access the folder, you should log in as root using sudo su or change the folder ownership to iotedge-user using chown command.
```
sudo su
cd /tmp/host-read-access
cat Hello-World.txt
```

If everything was successful, you should be able to see the contents of the Hello-World.txt file within the EFLOW virtual machine. Verify write access by creating a file inside the /tmp/host-read-write-access and then checking the contents of the new created file inside the Read-Write-Access Windows host folder.

Check shared folders

The following steps provide example EFLOW PowerShell commands to check the Windows shared folders and options (access permissions and mounting point) with the EFLOW virtual machine.

Open an elevated PowerShell session by starting with Run as Administrator.
List the information of the Windows shared folders under the root folder. For example, using the scenario in the previous section, we can list the information of both Read-Access and Read-Write-Access shared folders.
```
Get-EflowVmSharedFolder -sharedfolderRoot "C:\Shared\EFLOW-Shared" -hostFolderPath @("Read-Access", "Read-Write-Access")
```

For more information about the Get-EflowVmSharedFolder cmdlet, see PowerShell functions for IoT Edge for Linux on Windows.

Remove shared folders

The following steps provide example EFLOW PowerShell commands to stop sharing a Windows shared folder with the EFLOW virtual machine.

Open an elevated PowerShell session by starting with Run as Administrator.

Stop sharing the folder named Read-Access under the Root folder with the EFLOW virtual machine.

Remove-EflowVmSharedFolder -sharedfolderRoot "C:\Shared\EFLOW-Shared" -hostFolderPath "Read-Access"

For more information about the Remove-EflowVmSharedFolder cmdlet, see PowerShell functions for IoT Edge for Linux on Windows.

Next steps

Follow the steps in Common issues and resolutions for Azure IoT Edge for Linux on Windows to troubleshoot any issues encountered when setting up IoT Edge for Linux on Windows.