|
| 1 | +--- |
| 2 | +title: Share a Windows folder with Azure IoT Edge for Linux on Windows | Microsoft Docs |
| 3 | +description: How to share a Windows folder with the Azure IoT Edge for Linux on Windows virtual machine |
| 4 | +author: PatAltimore |
| 5 | +ms.reviewer: fcabrera |
| 6 | +ms.service: iot-edge |
| 7 | +services: iot-edge |
| 8 | +ms.topic: conceptual |
| 9 | +ms.date: 07/28/2022 |
| 10 | +ms.author: patricka |
| 11 | +--- |
| 12 | + |
| 13 | +# Share a Windows folder with Azure IoT Edge for Linux on Windows |
| 14 | + |
| 15 | +[!INCLUDE [iot-edge-version-all-supported](../../includes/iot-edge-version-all-supported.md)] |
| 16 | + |
| 17 | +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. |
| 18 | + |
| 19 | +This article shows you how to enable the folder sharing between the Windows host OS and the EFLOW virtual machine. |
| 20 | + |
| 21 | +## Prerequisites |
| 22 | +- Azure IoT Edge for Linux on Windows 1.3.1.30082 update or higher. For more information about EFLOW release notes, see [EFLOW Releases](https://aka.ms/AzEFLOW-Releases). |
| 23 | +- A machine with an x64/x86 processor. |
| 24 | +- Windows 11 Sun Valley 2 (build 22621) or higher. To get Windows SV2 update, you must be part of Windows Insider Program. For more information, see [Getting started with the Windows Insider Program](https://insider.windows.com/en-us/getting-started). After installation, you can verify your build version by running `winver` at the command prompt. |
| 25 | + |
| 26 | +>[!NOTE] |
| 27 | +>We plan to include support for Windows 10 21H2 (version 19044) version, Windows Server 2019/2022, and ARM64 processors in the upcoming months. |
| 28 | +
|
| 29 | +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](how-to-provision-single-device-linux-on-windows-symmetric.md) to install, deploy and provision EFLOW. |
| 30 | + |
| 31 | +## How it works? |
| 32 | + |
| 33 | +The Azure IoT Edge for Linux on Windows file and folder sharing mechanism is implemented using [virtiofs](https://virtio-fs.gitlab.io/) 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. |
| 34 | + |
| 35 | + |
| 36 | + |
| 37 | +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_. |
| 38 | + |
| 39 | +Before starting with the adding and removing share mechanisms, let's define four concepts: |
| 40 | + |
| 41 | +- **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. |
| 42 | +- **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. |
| 43 | +- **Mounting point**: Path inside the EFLOW VM where the Windows folder content is placed. |
| 44 | +- **Mounting option**: *Read-only* or *read and write* access. Controls the file access of the mounted folder inside the EFLOW VM. |
| 45 | + |
| 46 | +## Add shared folders |
| 47 | +The following steps provide example EFLOW PowerShell commands to share one or more Windows host OS folders with the EFLOW virtual machine. |
| 48 | + |
| 49 | +1. Start by creating a new root shared folder. Go to **File Explorer** and choose a location for the *root folder* and create the folder. |
| 50 | + |
| 51 | + For example, create a *root folder* under _C:\Shared_ named **EFLOW-Shared**. |
| 52 | + |
| 53 | +  |
| 54 | + |
| 55 | +1. 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. |
| 56 | + |
| 57 | + For example, create two folders one named **Read-Access** and one named **Read-Write-Access**. |
| 58 | + |
| 59 | +  |
| 60 | + |
| 61 | +1. Within the _Read-Access_ shared folder, create a sample file that we'll later read inside the EFLOW virtual machine. |
| 62 | + |
| 63 | + 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. |
| 64 | + |
| 65 | +1. 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](reference-iot-edge-for-linux-on-windows-functions.md). |
| 66 | + |
| 67 | + For example, using the previous scenario, we'll share the two *shared folders* we created under the *root folder*. |
| 68 | + - _Read-Access_ shared folder will be mounted in the EFLOW virtual machine under the path _/tmp/host-read-access_ with *read-only* access. |
| 69 | + - _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. |
| 70 | + |
| 71 | + Create the JSON configuration file named **sharedFolders.json** within the *root folder* *EFLOW-Shared* with the following contents: |
| 72 | + |
| 73 | + ```json |
| 74 | + [ |
| 75 | + { |
| 76 | + "sharedFolderRoot": "C:\\Shared\\EFLOW-Shared", |
| 77 | + "sharedFolders": [ |
| 78 | + { |
| 79 | + "hostFolderPath": "Read-Access", |
| 80 | + "readOnly": true, |
| 81 | + "targetFolderOnGuest": "/tmp/host-read-access" |
| 82 | + }, |
| 83 | + { |
| 84 | + "hostFolderPath": "Read-Write-Access", |
| 85 | + "readOnly": false, |
| 86 | + "targetFolderOnGuest": "/tmp/host-read-write-access" |
| 87 | + } |
| 88 | + ] |
| 89 | + } |
| 90 | + ] |
| 91 | + ``` |
| 92 | + |
| 93 | +1. Open an elevated _PowerShell_ session by starting with **Run as Administrator**. |
| 94 | + |
| 95 | +1. Create the shared folder assignation using the configuration file (_sharedFolders.json_) previously created. |
| 96 | + |
| 97 | + ```powershell |
| 98 | + Add-EflowVmSharedFolder -sharedFoldersJsonPath "C:\Shared\EFLOW-Shared\sharedFolders.json" |
| 99 | + ``` |
| 100 | + |
| 101 | +1. 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. |
| 102 | + ```powershell |
| 103 | + Connect-EflowVm |
| 104 | + ``` |
| 105 | + |
| 106 | +1. Go to the _Read-Access_ shared folder (mounted under _/tmp/host-read-access_) and check the content of the _Hello-World.txt_ file. |
| 107 | + |
| 108 | + >[!NOTE] |
| 109 | + >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. |
| 110 | + |
| 111 | + ```bash |
| 112 | + sudo su |
| 113 | + cd /tmp/host-read-access |
| 114 | + cat Hello-World.txt |
| 115 | + ``` |
| 116 | +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. |
| 117 | + |
| 118 | +## Check shared folders |
| 119 | +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. |
| 120 | + |
| 121 | +1. Open an elevated PowerShell session by starting with **Run as Administrator**. |
| 122 | + |
| 123 | +1. List the information of the Windows shared folders under the *root folder*. |
| 124 | + For example, using the scenario in the previous section, we can list the information of both _Read-Access_ and _Read-Write-Access_ shared folders. |
| 125 | + ```powershell |
| 126 | + Get-EflowVmSharedFolder -sharedfolderRoot "C:\Shared\EFLOW-Shared" -hostFolderPath @("Read-Access", "Read-Write-Access") |
| 127 | + ``` |
| 128 | + |
| 129 | +For more information about the `Get-EflowVmSharedFolder` cmdlet, see [PowerShell functions for IoT Edge for Linux on Windows](reference-iot-edge-for-linux-on-windows-functions.md). |
| 130 | + |
| 131 | + |
| 132 | +## Remove shared folders |
| 133 | +The following steps provide example EFLOW PowerShell commands to stop sharing a Windows shared folder with the EFLOW virtual machine. |
| 134 | + |
| 135 | +1. Open an elevated PowerShell session by starting with **Run as Administrator**. |
| 136 | + |
| 137 | +1. Stop sharing the folder named _Read-Access_ under the **Root folder** with the EFLOW virtual machine. |
| 138 | + ```powershell |
| 139 | + Remove-EflowVmSharedFolder -sharedfolderRoot "C:\Shared\EFLOW-Shared" -hostFolderPath "Read-Access" |
| 140 | + ``` |
| 141 | + |
| 142 | +For more information about the `Remove-EflowVmSharedFolder` cmdlet, see [PowerShell functions for IoT Edge for Linux on Windows](reference-iot-edge-for-linux-on-windows-functions.md). |
| 143 | + |
| 144 | +## Next steps |
| 145 | +Follow the steps in [Common issues and resolutions for Azure IoT Edge for Linux on Windows](troubleshoot-iot-edge-for-linux-on-windows-common-errors.md) to troubleshoot any issues encountered when setting up IoT Edge for Linux on Windows. |
0 commit comments