PowerShell scripts for IoT Edge with Windows containers
Applies to: 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: