Edit

Share via

PowerShell requests for Run command on Azure Arc-enabled servers (Preview)

  • Article

Using the PowerShell commands for Connected Machine Run Command, you can remotely and securely execute scripts or commands on Arc-enabled virtual machines without connecting directly to them through Remote Desktop Protocol or SSH.

This article provides examples that use several PowerShell commands to help you understand how to use PowerShell to execute scripts or commands on your Arc-enabled server.

Prerequisites

  • The Connected Machine agent version on the Arc-enabled server must be 1.33 or higher.

PowerShell sample requests

The following examples use various PowerShell commands to work with Run commands on an Arc-enabled server.

Execute a script on a machine

This command delivers the script to the machine, executes it, and returns the captured output.

New-AzConnectedMachineRunCommand -ResourceGroupName "myRG" -MachineName "myMachine" -Location "eastus" -RunCommandName "RunCommandName" –SourceScript "echo Hello World!"

Note

You can add multiple commands in the -SourceScript parameter. Use ; to separate each command. Example: –SourceScript "id; echo Hello World!"

Execute a script on the machine using a script file in storage

This command directs the Connected Machine agent to a shared access signature (SAS) URI for a storage blob where a script was uploaded, then directs the agent to execute the script and return the captured output.

New-AzConnectedMachineRunCommand -ResourceGroupName "MyRG0" -MachineName "MyMachine" -RunCommandName "MyRunCommand" -Location "eastus" -SourceScriptUri “< SAS URI of a storage blob with read access or public URI>”

Note

The scriptUri is a shared access signature (SAS) URI for the storage blob, and it must provide read access to the blob. An expiry time of 24 hours is suggested for the SAS URI. You can generate a SAS URI on Azure portal using blobs options or SAS token using New-AzStorageBlobSASToken. If generating SAS token using New-AzStorageBlobSASToken, the SAS URI format is: base blob URL + "?" + the SAS token from New-AzStorageBlobSASToken.

List all deployed Run command resources on a machine

This command returns a full list of previously deployed Run Commands along with their properties.

Get-AzConnectedMachineRunCommand -ResourceGroupName "myRG" -MachineName "myMachine"

Get execution status and results

This command retrieves current execution progress for a Run command, including latest output, start/end time, exit code, and terminal state of the execution.

Get-AzConnectedMachineRunCommand -ResourceGroupName "myRG" - MachineName "myMachine" -RunCommandName "RunCommandName"

Get status information for a Run command through Instance View

Get status information for a Run command on machine with Instance View. Instance View contains the execution state of the Run command (succeeded, failed, and so on), exit code, standard output, and standard error generated by executing the script. A nonzero exit code indicates an unsuccessful execution.

Get-AzConnectedMachineRunCommand -ResourceGroupName "MyRG" -MachineName "MyMachine" -RunCommandName "MyRunCommand"

In addition to other information, the response returns these fields:

  • InstanceViewExecutionState: Status of the Run command script. Refer to this state to know whether your script was successful or not.

  • ProvisioningState: Status of general extension provisioning end to end (whether extension platform was able to trigger the Run command script or not).

Create or update Run Command on a machine and capture standard output and standard error messages

Create or update Run command on a machine and stream standard output and standard error messages to output and error Append blobs.

New-AzConnectedMachineRunCommand -ResourceGroupName "MyRG0" - MachineName "MyMachine" -RunCommandName "MyRunCommand3" -Location "eastus" -SourceScript "id; echo HelloWorld" -OutputBlobUri <OutPutBlobUrI> -ErrorBlobUri <ErrorBlobUri>

Note

Output and error blobs must be the AppendBlob type and their SAS URIs must provide read, append, create, and write access to the blob. An expiration time of 24 hours is suggested for SAS URI. If the output or error blob doesn't exist, a blob of type AppendBlob is created. You can generate a SAS URIs on the Azure portal using blob's options or SAS token from using New-AzStorageBlobSASToken.

Create or update Run Command on a machine as a different user

Create or update Run command on a machine as a different user with RunAsUser and RunAsPassword parameters.

Before you can use these parameters, you need to:

  • Contact the administrator of the machine and make sure the user has access to the machine.
  • Make sure the user has access to the resources accessed by the Run command. Examples: directories, files, network, and so on.
  • On a Windows machine, make sure 'Secondary Logon' is running.
New-AzMachineRunCommand -ResourceGroupName "MyRG0" -MachineName "MyMachine" -RunCommandName "MyRunCommand" -Location "eastus" -SourceScript "id; echo HelloWorld" -RunAsUser myusername -RunAsPassword mypassword

Create or update Run command on a machine with a local script file

Create or update Run Command on a machine using a local script file on the client machine where cmdlet is executed.

New-AzConnectedMachineRunCommand -ResourceGroupName "MyRG0" -VMName "MyMachine" -RunCommandName "MyRunCommand" -Location "eastus" -ScriptLocalPath "C:\MyScriptsDir\MyScript.ps1"

Create or update Run command on a machine while passing sensitive inputs to the script

Use ProtectedParameter to pass any sensitive inputs to a script such as passwords or keys.

$privateParametersArray = @{name='inputText';value='privateParam1value'}

New-AzConnectedMachineRunCommand -MachineName "MyMachine" -ResourceGroupName "MyRG0" -RunCommandName "MyRunCommand" -Location "eastus" -SourceScriptUri <SourceScriptUri> -ProtectedParameter $privateParametersArray

Sample script for capturing inputText:

param ([string]$inputText)
Write-Output $inputText

You can also pass public parameters in a similar way using Parameter.

  • Windows - Parameter and ProtectedParameter are passed to a script similar to the following example: myscript.ps1 -publicParam1 publicParam1value -publicParam2 publicParam2value -secret1 secret1value -secret2 secret2value

  • Linux - A named Parameter and its values are set to environment config, which should be accessible within the PowerShell script. For Nameless arguments, pass an empty string to name input. Nameless arguments are passed to script similar to the following example: myscript.sh publicParam1value publicParam2value secret1value secret2value

Delete RunCommand resource from the machine

Remove the Run Command resource previously deployed on the machine. If the script execution is still in progress, execution terminates.

Remove-AzConnectedMachineRunCommand -ResourceGroupName "myRG" -MachineName "myMachine" -RunCommandName "RunCommandName"

Related content