PowerShell functions for IoT Edge for Linux on Windows

Applies to: IoT Edge 1.5 IoT Edge 1.4

Understand the PowerShell functions that deploy, provision, and get the status of your IoT Edge for Linux on Windows (EFLOW) virtual machine.

Prerequisites

The commands described in this article are from the AzureEFLOW.psm1 file, which can be found on your system in your WindowsPowerShell directory under C:\Program Files\WindowsPowerShell\Modules\AzureEFLOW.

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:

1. In an elevated PowerShell session, run each of the following commands to download IoT Edge for Linux on Windows.

   • X64/AMD64

   $msiPath = $([io.Path]::Combine($env:TEMP, 'AzureIoTEdge.msi'))
   $ProgressPreference = 'SilentlyContinue'
   Invoke-WebRequest "https://aka.ms/AzEFLOWMSI_1_4_LTS_X64" -OutFile $msiPath
   

   • ARM64

   $msiPath = $([io.Path]::Combine($env:TEMP, 'AzureIoTEdge.msi'))
   $ProgressPreference = 'SilentlyContinue'
   Invoke-WebRequest "https://aka.ms/AzEFLOWMSI_1_4_LTS_ARM64" -OutFile $msiPath
   

2. Install IoT Edge for Linux on Windows on your device.

   Start-Process -Wait msiexec -ArgumentList "/i","$([io.Path]::Combine($env:TEMP, 'AzureIoTEdge.msi'))","/qn"
   

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

3. Set the execution policy on the target device to at least AllSigned.

   Set-ExecutionPolicy -ExecutionPolicy AllSigned -Force
   

Add-EflowNetwork

The Add-EflowNetwork command adds a new network to the EFLOW virtual machine. This command takes two parameters.

It returns an object that contains four properties:

• Name
• AllocationMethod
• Cidr
• Type

For more information, use the command Get-Help Add-EflowNetwork -full.

Add-EflowVmEndpoint

The Add-EflowVmEndpoint command adds a new network endpoint to the EFLOW virtual machine. Use the optional parameters to set a Static IP.

It returns an object that contains four properties:

• Name
• MacAddress
• HealthStatus
• IpConfiguration

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

Add-EflowVmSharedFolder

The Add-EflowVmSharedFolder command allows sharing one or more Windows host OS folders with the EFLOW virtual machine.

The JSON configuration file must have the following structure:

• sharedFOlderRoot : Path to the Windows root folder that contains all the folders to be shared with the EFLOW virtual machine.
• hostFolderPath: Relative path (to the parent root folder) of the folder to be shared with the EFLOW VM.
• readOnly: Defines if the shared folder is writeable or read-only from the EFLOW virtual machine - Values: false or true.
• targetFolderOnGuest : Folder path inside the EFLOW virtual machine where Windows host OS folder is mounted.

[
   {
      "sharedFolderRoot": "<shared-folder-root-windows-path>",
      "sharedFolders": [ 
        { "hostFolderPath": "<path-shared-folder>", 
            "readOnly": "<read-only>", 
            "targetFolderOnGuest": "<linux-mounting-point>" 
        }
      ]
   }
]

For more information, use the command Get-Help Add-EflowVmSharedFolder -full.

Connect-EflowVm

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.

This command only works on a PowerShell session running on the host device. It won't work when using Windows Admin Center or PowerShell ISE.

For more information, use the command Get-Help Connect-EflowVm -full.

Copy-EflowVmFile

The Copy-EflowVmFile command copies file to or from the virtual machine using SCP. Use the optional parameters to specify the source and destination file paths and the direction of the copy.

The user iotedge-user must have read permission to any origin directories or write permission to any destination directories on the virtual machine.

For more information, use the command Get-Help Copy-EflowVMFile -full.

Deploy-Eflow

The Deploy-Eflow command is the main deployment method. The deployment command creates the virtual machine, provisions files, and deploys the IoT Edge agent module. While none of the parameters are required, they can be used to modify settings for the virtual machine during creation.

For more information, use the command Get-Help Deploy-Eflow -full.

Get-EflowHostConfiguration

The Get-EflowHostConfiguration command returns the host configuration. This command takes no parameters. It returns an object that contains four properties:

• FreePhysicalMemoryInMB
• NumberOfLogicalProcessors
• DiskInfo
• GpuInfo

For more information, use the command Get-Help Get-EflowHostConfiguration -full.

Get-EflowLogs

The Get-EflowLogs command collects and bundles logs from the IoT Edge for Linux on Windows deployment and installation. It outputs the bundled logs in the form of a .zip folder.

For more information, use the command Get-Help Get-EflowLogs -full.

Get-EflowNetwork

The Get-EflowNetwork command returns a list of the networks assigned to the EFLOW virtual machine. Use the optional parameter to get a specific network.

It returns a list of objects that contains four properties:

• Name
• AllocationMethod
• Cidr
• Type

For more information, use the command Get-Help Get-EflowNetwork -full.

Get-EflowVm

The Get-EflowVm command returns the virtual machine's current configuration. This command takes no parameters. It returns an object that contains four properties:

• VmConfiguration
• VmPowerState
• EdgeRuntimeVersion
• EdgeRuntimeStatus
• SystemStatistics

To view a specific property in a readable list, run the Get-EflowVM command with the property expanded. For example:

Get-EflowVM | Select -ExpandProperty VmConfiguration | Format-List

For more information, use the command Get-Help Get-EflowVm -full.

Get-EflowVmAddr

The Get-EflowVmAddr command is used to query the virtual machine's current IP and MAC address. This command exists to account for the fact that the IP and MAC address can change over time.

For additional information, use the command Get-Help Get-EflowVmAddr -full.

Get-EflowVmEndpoint

The Get-EflowVmEndpoint command returns a list of the network endpoints assigned to the EFLOW virtual machine. Use the optional parameter to get a specific network endpoint.

It returns a list of objects that contains four properties:

• Name
• MacAddress
• HealthStatus
• IpConfiguration

For more information, use the command Get-Help Get-EflowVmEndpoint -full.

Get-EflowVmFeature

The Get-EflowVmFeature command returns the status of the enablement of IoT Edge for Linux on Windows features.

For more information, use the command Get-Help Get-EflowVmFeature -full.

Get-EflowVmName

The Get-EflowVmName command returns the virtual machine's current hostname. This command exists to account for the fact that the Windows hostname can change over time.

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

Get-EflowVmSharedFolder

The Get-EflowVmSharedFolder command returns the information about one or more Windows host OS folders shared with the EFLOW virtual machine.

It returns a list of objects that contains three properties:

• hostFolderPath: Relative path (to the parent root folder) of the folder shared with the EFLOW VM.
• readOnly: Defines if the shared folder is writeable or read-only from the EFLOW virtual machine - Values: false or true.
• targetFolderOnGuest: Folder path inside the EFLOW virtual machine where the Windows folder is mounted.

For more information, use the command Get-Help Get-EflowVmSharedFolder -full.

Get-EflowVmTelemetryOption

The Get-EflowVmTelemetryOption command displays the status of the telemetry (either Optional or Required) inside the virtual machine.

For more information, use the command Get-Help Get-EflowVmTelemetryOption -full.

Get-EflowVmTpmProvisioningInfo

The Get-EflowVmTpmProvisioningInfo command returns the TPM provisioning information. This command takes no parameters. It returns an object that contains two properties:

• Endorsement Key
• Registration ID

For more information, use the command Get-Help Get-EflowVmTpmProvisioningInfo -full.

Invoke-EflowVmCommand

The Invoke-EflowVMCommand command executes a Linux command inside the virtual machine and returns the output. This command only works for Linux commands that return a finite output. It cannot be used for Linux commands that require user interaction or that run indefinitely.

The following optional parameters can be used to specify the command in advance.

For more information, use the command Get-Help Invoke-EflowVmCommand -full.

Provision-EflowVm

The Provision-EflowVm command adds the provisioning information for your IoT Edge device to the virtual machine's IoT Edge config.yaml file.

For more information, use the command Get-Help Provision-EflowVm -full.

Remove-EflowNetwork

The Remove-EflowNetwork command removes an existing network attached to the EFLOW virtual machine. This command takes one parameter.

For more information, use the command Get-Help Remove-EflowNetwork -full.

Remove-EflowVmEndpoint

The Remove-EflowVmEndpoint command removes an existing network endpoint attached to the EFLOW virtual machine. This command takes one parameter.

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

Remove-EflowVmSharedFolder

The Remove-EflowVmSharedFolder command stops sharing the Windows host OS folder to the EFLOW virtual machine. This command takes two parameters.

For more information, use the command Get-Help Remove-EflowVmSharedFolder -full.

Set-EflowVM

The Set-EflowVM command updates the virtual machine configuration with the requested properties. Use the optional parameters to define a specific configuration for the virtual machine.

For more information, use the command Get-Help Set-EflowVM -full.

Set-EflowVmDNSServers

The Set-EflowVmDNSServers command configures the DNS servers for EFLOW virtual machine.

For more information, use the command Get-Help Set-EflowVmDNSServers -full.

Set-EflowVmFeature

The Set-EflowVmFeature command enables or disables the status of IoT Edge for Linux on Windows features.

For more information, use the command Get-Help Set-EflowVmFeature -full.

Set-EflowVmTelemetryOption

The Set-EflowVmTelemetryOption command enables or disables the optional telemetry inside the virtual machine.

For more information, use the command Get-Help Set-EflowVmTelemetryOption -full.

Start-EflowVm

The Start-EflowVm command starts the virtual machine. If the virtual machine is already started, no action is taken.

For more information, use the command Get-Help Start-EflowVm -full.

Stop-EflowVm

The Stop-EflowVm command stops the virtual machine. If the virtual machine is already stopped, no action is taken.

For more information, use the command Get-Help Stop-EflowVm -full.

Verify-EflowVm

The Verify-EflowVm command is an exposed function that checks whether the IoT Edge for Linux on Windows virtual machine was created. It takes only common parameters, and it returns True if the virtual machine was created and False if not.

For more information, use the command Get-Help Verify-EflowVm -full.

Next steps

Learn how to use these commands to install and provision IoT Edge for Linux on Windows in the following article:

• Install Azure IoT Edge for Linux on Windows