Skip to content

Commit 2b89580

Browse files
Court72Court72
authored
Merge pull request #205966 from fcabrera23/eflow-sharing
Eflow sharing
2 parents 42a785e + 1fa16b3 commit 2b89580

File tree

6 files changed

+245
-3
lines changed

6 files changed

+245
-3
lines changed

‎articles/iot-edge/TOC.yml

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -53,6 +53,8 @@
5353
href: how-to-access-dtpm.md
5454
- name: GPU acceleration
5555
href: gpu-acceleration.md
56+
- name: Shared folders
57+
href: how-to-share-windows-folder-to-vm.md
5658
- name: Develop and debugging
5759
href: tutorial-develop-for-linux-on-windows.md
5860
- name: Troubleshoot

‎articles/iot-edge/how-to-share-windows-folder-to-vm.md

Lines changed: 145 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,145 @@
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+
![Windows folder shared with the EFLOW virtual machine using Virtio-FS technology](media/how-to-share-windows-folder-to-vm/folder-sharing-virtiofs.png)
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+
![Windows root folder](media/how-to-share-windows-folder-to-vm/root-folder.png)
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+
![Windows shared folders](media/how-to-share-windows-folder-to-vm/shared-folders.png)
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.

‎articles/iot-edge/media/how-to-share-windows-folder-to-vm/folder-sharing-virtiofs.png

94.5 KB
Loading

‎articles/iot-edge/media/how-to-share-windows-folder-to-vm/root-folder.png

27.7 KB
Loading

‎articles/iot-edge/media/how-to-share-windows-folder-to-vm/shared-folders.png

31 KB
Loading

‎articles/iot-edge/reference-iot-edge-for-linux-on-windows-functions.md

Lines changed: 98 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@ description: Reference information for Azure IoT Edge for Linux on Windows Power
44
author: PatAltimore
55

66
ms.author: fcabrera
7-
ms.date: 07/05/2022
7+
ms.date: 07/28/2022
88
ms.topic: reference
99
ms.service: iot-edge
1010
services: iot-edge
@@ -22,13 +22,38 @@ The commands described in this article are from the `AzureEFLOW.psm1` file, whic
2222

2323
If you don't have the **AzureEflow** folder in your PowerShell directory, use the following steps to download and install Azure IoT Edge for Linux on Windows:
2424

25+
<!-- 1.1 -->
26+
:::moniker range="iotedge-2018-06"
2527
1. In an elevated PowerShell session, run each of the following commands to download IoT Edge for Linux on Windows.
2628

2729
```powershell
2830
$msiPath = $([io.Path]::Combine($env:TEMP, 'AzureIoTEdge.msi'))
2931
$ProgressPreference = 'SilentlyContinue'
3032
Invoke-WebRequest "https://aka.ms/AzEflowMSI" -OutFile $msiPath
3133
```
34+
:::moniker-end
35+
<!-- end iotedge-2018-06 -->
36+
37+
<!-- iotedge-2020-11 -->
38+
:::moniker range=">=iotedge-2020-11"
39+
1. In an elevated PowerShell session, run each of the following commands to download IoT Edge for Linux on Windows.
40+
41+
* **X64/AMD64**
42+
```powershell
43+
$msiPath = $([io.Path]::Combine($env:TEMP, 'AzureIoTEdge.msi'))
44+
$ProgressPreference = 'SilentlyContinue'
45+
Invoke-WebRequest "https://aka.ms/AzEFLOWMSI-CR-X64" -OutFile $msiPath
46+
```
47+
48+
* **ARM64**
49+
```powershell
50+
$msiPath = $([io.Path]::Combine($env:TEMP, 'AzureIoTEdge.msi'))
51+
$ProgressPreference = 'SilentlyContinue'
52+
Invoke-WebRequest "https://aka.ms/AzEFLOWMSI-CR-ARM64" -OutFile $msiPath
53+
```
54+
:::moniker-end
55+
<!-- end iotedge-2020-11 -->
56+
3257

3358
1. Install IoT Edge for Linux on Windows on your device.
3459

@@ -38,7 +63,7 @@ If you don't have the **AzureEflow** folder in your PowerShell directory, use th
3863

3964
You can specify custom installation and VHDX directories by adding `INSTALLDIR="<FULLY_QUALIFIED_PATH>"` and `VHDXDIR="<FULLY_QUALIFIED_PATH>"` parameters to the install command.
4065

41-
1. Set the execution policy on the target device to `AllSigned` if it is not already.
66+
1. Set the execution policy on the target device to at least `AllSigned`.
4267

4368
```powershell
4469
Set-ExecutionPolicy -ExecutionPolicy AllSigned -Force
@@ -83,6 +108,41 @@ It returns an object that contains four properties:
83108

84109
For more information, use the command `Get-Help Add-EflowVmEndpoint -full`.
85110

111+
<!-- iotedge-2020-11 -->
112+
:::moniker range=">=iotedge-2020-11"
113+
## Add-EflowVmSharedFolder
114+
115+
The **Add-EflowVmSharedFolder** command allows sharing one or more Windows host OS folders with the EFLOW virtual machine.
116+
117+
| Parameter | Accepted values | Comments |
118+
| --------- | --------------- | -------- |
119+
| sharedFoldersJsonPath | String | Path to the **Shared Folders** JSON configuration file. |
120+
121+
The JSON configuration file must have the following structure:
122+
123+
- **sharedFOlderRoot** : Path to the Windows root folder that contains all the folders to be shared with the EFLOW virtual machine.
124+
- **hostFolderPath**: Relative path (to the parent root folder) of the folder to be shared with the EFLOW VM.
125+
- **readOnly**: Defines if the shared folder will be writeable or read-only from the EFLOW virtual machine - Values: **false** or **true**.
126+
- **targetFolderOnGuest** : Folder path inside the EFLOW virtual machine where Windows host OS folder will be mounted.
127+
128+
```json
129+
[
130+
{
131+
"sharedFolderRoot": "<shared-folder-root-windows-path>",
132+
"sharedFolders": [
133+
{ "hostFolderPath": "<path-shared-folder>",
134+
"readOnly": "<read-only>",
135+
"targetFolderOnGuest": "<linux-mounting-point>"
136+
}
137+
]
138+
}
139+
]
140+
```
141+
For more information, use the command `Get-Help Add-EflowVmSharedFolder -full`.
142+
143+
:::moniker-end
144+
<!-- end iotedge-2020-11 -->
145+
86146
## Connect-EflowVm
87147

88148
The **Connect-EflowVm** command connects to the virtual machine using SSH. The only account allowed to SSH to the virtual machine is the user that created it.
@@ -140,7 +200,7 @@ The **Deploy-Eflow** command is the main deployment method. The deployment comma
140200
| memoryInMB | Integer **even** value between 1024 and the maximum amount of free memory of the device |Memory allocated for the VM.<br><br>**Default value**: 1024 MB. |
141201
| vmDiskSize | Between 21 GB and 2 TB | Maximum logical disk size of the dynamically expanding virtual hard disk.<br><br>**Default value**: 29 GB. <br><br>**Note**: Either _vmDiskSize_ or _vmDataSize_ can be used, but not both together. |
142202
| vmDataSize | Between 2 GB and 2 TB | Maximum data partition size of the resulting hard disk, in GB.<br><br>**Default value**: 10 GB. <br><br>**Note**: Either _vmDiskSize_ or _vmDataSize_ can be used, but not both together. |
143-
| vmLogSize | **Small** or **Large** | Specificy the log partition size. Small = 1GB, Large = 6GB.<br><br>**Default value**: Small. |
203+
| vmLogSize | **Small** or **Large** | Specify the log partition size. Small = 1GB, Large = 6GB.<br><br>**Default value**: Small. |
144204
| vswitchName | Name of the virtual switch | Name of the virtual switch assigned to the EFLOW VM. |
145205
| vswitchType | **Internal** or **External** | Type of the virtual switch assigned to the EFLOW VM. |
146206
| ip4Address | IPv4 Address in the range of the DCHP Server Scope | Static Ipv4 address of the EFLOW VM. |
@@ -150,6 +210,7 @@ The **Deploy-Eflow** command is the main deployment method. The deployment comma
150210
| gpuPassthroughType | **DirectDeviceAssignment**, **ParaVirtualization**, or none (CPU only) | GPU Passthrough type |
151211
| gpuCount | Integer value between 1 and the number of the device's GPU cores | Number of GPU devices for the VM. <br><br>**Note**: If using ParaVirtualization, make sure to set gpuCount = 1 |
152212
| customSsh | None | Determines whether user wants to use their custom OpenSSH.Client installation. If present, ssh.exe must be available to the EFLOW PSM |
213+
| sharedFoldersJsonPath | String | Path to the **Shared Folders** JSON configuration file. |
153214
:::moniker-end
154215
<!-- end iotedge-2020-11 -->
155216

@@ -249,6 +310,26 @@ The **Get-EflowVmName** command returns the virtual machine's current hostname.
249310

250311
For more information, use the command `Get-Help Get-EflowVmName -full`.
251312

313+
<!-- iotedge-2020-11 -->
314+
:::moniker range=">=iotedge-2020-11"
315+
## Get-EflowVmSharedFolder
316+
317+
The **Get-EflowVmSharedFolder** command returns the information about one or more Windows host OS folders shared with the EFLOW virtual machine.
318+
319+
| Parameter | Accepted values | Comments |
320+
| --------- | --------------- | -------- |
321+
| sharedfolderRoot | String | Path to the Windows host OS shared root folder.|
322+
| hostFolderPath | String or List | Relative path/paths (to the root folder) to the Windows host OS shared folder/s.|
323+
324+
It returns a list of objects that contains three properties:
325+
- **hostFolderPath**: Relative path (to the parent root folder) of the folder shared with the EFLOW VM.
326+
- **readOnly**: Defines if the shared folder is writeable or read-only from the EFLOW virtual machine - Values: **false** or **true**.
327+
- **targetFolderOnGuest**: Folder path inside the EFLOW virtual machine where the Windows folder is mounted.
328+
329+
For more information, use the command `Get-Help Get-EflowVmSharedFolder -full`.
330+
:::moniker-end
331+
<!-- end iotedge-2020-11 -->
332+
252333
## Get-EflowVmTelemetryOption
253334

254335
The **Get-EflowVmTelemetryOption** command displays the status of the telemetry (either **Optional** or **Required**) inside the virtual machine.
@@ -316,6 +397,20 @@ The **Remove-EflowVmEndpoint** command removes an existing network endpoint atta
316397

317398
For more information, use the command `Get-Help Remove-EflowVmEndpoint -full`.
318399

400+
<!-- iotedge-2020-11 -->
401+
:::moniker range=">=iotedge-2020-11"
402+
## Remove-EflowVmSharedFolder
403+
404+
The **Remove-EflowVmSharedFolder** command stops sharing the Windows host OS folder to the EFLOW virtual machine. This command takes two parameters.
405+
406+
| Parameter | Accepted values | Comments |
407+
| --------- | --------------- | -------- |
408+
| sharedfolderRoot | String | Path to the Windows host OS shared root folder.|
409+
| hostFolderPath | String or List | Relative path/paths (to the root folder) to the Windows host OS shared folder/s.|
410+
411+
For more information, use the command `Get-Help Remove-EflowVmSharedFolder -full`.
412+
:::moniker-end
413+
<!-- end iotedge-2020-11 -->
319414

320415
## Set-EflowVM
321416

0 commit comments

Comments
 (0)