Share via


PowerShell scripts for IoT Edge with Windows containers

Applies to: yes icon IoT Edge 1.1

Important

IoT Edge 1.1 end of support date was December 13, 2022. Check the Microsoft Product Lifecycle for information about how this product, service, technology, or API is supported. For more information about updating to the latest version of IoT Edge, see Update IoT Edge.

Understand the PowerShell scripts that install, update, or uninstall IoT Edge on Windows devices.

The commands described in this article are from the IoTEdgeSecurityDaemon.ps1 file that is released with every IoT Edge release. The latest version of the script is always available at aka.ms/iotedge-win.

You can run any of the commands using the Invoke-WebRequest cmdlet to access the latest script version. For example:

. {Invoke-WebRequest -useb https://aka.ms/iotedge-win} | Invoke-Expression; `
Deploy-IoTEdge

You can also download this script, or a version of the script from a specific release, to run the commands. For example:

. <path>\IoTEdgeSecurityDaemon.ps1
Deploy-IoTEdge

The provided script is signed to increase security. You can verify the signature by downloading the script to your device then running the following PowerShell command:

Get-AuthenticodeSignature "C:\<path>\IotEdgeSecurityDaemon.ps1"

The output status is Valid if the signature is verified.

Deploy-IoTEdge

The Deploy-IoTEdge command downloads and deploys the IoT Edge Security Daemon and its dependencies. The deployment command accepts these common parameters, among others. For the full list, use the command Get-Help Deploy-IoTEdge -full.

Parameter Accepted values Comments
ContainerOs Windows or Linux If no container operating system is specified, Windows is the default value.

For Windows containers, IoT Edge uses the Moby container engine included in the installation. For Linux containers, you need to install a container engine before starting the installation.
Proxy Proxy URL Include this parameter if your device needs to go through a proxy server to reach the internet. For more information, see Configure an IoT Edge device to communicate through a proxy server.
OfflineInstallationPath Directory path If this parameter is included, the installer will check the listed directory for the IoT Edge cab and VC Runtime MSI files required for installation. Any files not found in the directory are downloaded. If both files are in the directory, you can install IoT Edge without an internet connection. You can also use this parameter to use a specific version.
InvokeWebRequestParameters Hashtable of parameters and values During installation, several web requests are made. Use this field to set parameters for those web requests. This parameter is useful to configure credentials for proxy servers. For more information, see Configure an IoT Edge device to communicate through a proxy server.
RestartIfNeeded none This flag allows the deployment script to restart the machine without prompting, if necessary.

Initialize-IoTEdge

The Initialize-IoTEdge command configures IoT Edge with your device connection string and operational details. Much of the information generated by this command is then stored in the iotedge\config.yaml file. The initialization command accepts these common parameters, among others. For the full list, use the command Get-Help Initialize-IoTEdge -full.

Parameter Accepted values Comments
ManualConnectionString None Switch parameter. Default value. If no provisioning type is specified, manual provisioning with a connection string is the default value.

Declares that you will provide a device connection string to provision the device manually.
ManualX509 None Switch parameter. If no provisioning type is specified, manual provisioning with a connection string is the default value.

Declares that you will provide an identity certificate and private key to provision the device manually.
DpsTpm None Switch parameter. If no provisioning type is specified, manual provisioning with a connection string is the default value.

Declares that you will provide a Device Provisioning Service (DPS) scope ID and your device's Registration ID to provision through DPS.
DpsSymmetricKey None Switch parameter. If no provisioning type is specified, manual provisioning with a connection string is the default value.

Declares that you will provide a Device Provisioning Service (DPS) scope ID and your device's Registration ID to provision through DPS, along with a symmetric key for attestation.
DpsX509 None Switch parameter. If no provisioning type is specified, manual provisioning with a connection string is the default value.

Declares that you will provide a Device Provisioning Service (DPS) scope ID and your device's Registration ID to provision through DPS, along with an X.509 identity certificate and private key for attestation.
DeviceConnectionString A connection string from an IoT Edge device registered in an IoT Hub, in single quotes Required for manual provisioning with a connection string. If you don't provide a connection string in the script parameters, you will be prompted for one.
IotHubHostName The hostname of the IoT hub that a device connects to. Required for manual provisioning with X.509 certificates. Takes the format {hub name}.azure-devices.net.
DeviceId The device ID from a registered device identity in IoT Hub. Required for manual provisioning with X.509 certificates.
ScopeId A scope ID from an instance of Device Provisioning Service associated with your IoT Hub. Required for DPS provisioning. If you don't provide a scope ID in the script parameters, you will be prompted for one.
RegistrationId A registration ID generated by your device Required for DPS provisioning if using TPM or symmetric key attestation. Optional if using X.509 certificate attestation.
X509IdentityCertificate The URI path to the X.509 device identity certificate on the device. Required for either manual or DPS provisioning if using X.509 certificate attestation.
X509IdentityPrivateKey The URI path to the X.509 device identity certificate key on the device. Required for either manual or DPS provisioning if using X.509 certificate attestation.
SymmetricKey The symmetric key used to provision the IoT Edge device identity when using DPS Required for DPS provisioning if using symmetric key attestation.
ContainerOs Windows or Linux If no container operating system is specified, Windows is the default value.

For Windows containers, IoT Edge uses the Moby container engine included in the installation. For Linux containers, you need to install a container engine before starting the installation.
DeviceCACertificate The URI path to the X.509 device CA certificate on the device. Can also be configured in the C:\ProgramData\iotedge\config.yaml file. For more information, see Manage certificates on an IoT Edge device.
DeviceCAPrivateKey The URI path to the X.509 device CA private key on the device. Can also be configured in the C:\ProgramData\iotedge\config.yaml file. For more information, see Manage certificates on an IoT Edge device.
InvokeWebRequestParameters Hashtable of parameters and values During installation, several web requests are made. Use this field to set parameters for those web requests. This parameter is useful to configure credentials for proxy servers. For more information, see Configure an IoT Edge device to communicate through a proxy server.
AgentImage IoT Edge agent image URI By default, a new IoT Edge installation uses the latest rolling tag for the IoT Edge agent image. Use this parameter to set a specific tag for the image version, or to provide your own agent image. For more information, see Understand IoT Edge tags.
Username Container registry username Use this parameter only if you set the -AgentImage parameter to a container in a private registry. Provide a username with access to the registry.
Password Secure password string Use this parameter only if you set the -AgentImage parameter to a container in a private registry. Provide the password to access the registry.

Update-IoTEdge

Parameter Accepted values Comments
ContainerOs Windows or Linux If no container OS is specified, Windows is the default value. For Windows containers, a container engine will be included in the installation. For Linux containers, you need to install a container engine before starting the installation.
Proxy Proxy URL Include this parameter if your device needs to go through a proxy server to reach the internet. For more information, see Configure an IoT Edge device to communicate through a proxy server.
InvokeWebRequestParameters Hashtable of parameters and values During installation, several web requests are made. Use this field to set parameters for those web requests. This parameter is useful to configure credentials for proxy servers. For more information, see Configure an IoT Edge device to communicate through a proxy server.
OfflineInstallationPath Directory path If this parameter is included, the installer will check the listed directory for the IoT Edge cab and VC Runtime MSI files required for installation. Any files not found in the directory are downloaded. If both files are in the directory, you can install IoT Edge without an internet connection. You can also use this parameter to use a specific version.
RestartIfNeeded none This flag allows the deployment script to restart the machine without prompting, if necessary.

Uninstall-IoTEdge

Parameter Accepted values Comments
Force none This flag forces the uninstallation in case the previous attempt to uninstall was unsuccessful.
RestartIfNeeded none This flag allows the uninstall script to restart the machine without prompting, if necessary.

Next steps

Learn how to use these commands in the following article: