Skip to content

Commit 03f0969

Browse files
v-shilsv-shils
authored
Merge pull request #265628 from johnmarco/jm-arc-run-command-update
ARC: Update Run Command article
2 parents 67291c7 + 3e5e440 commit 03f0969

File tree

1 file changed

+176
-1
lines changed

1 file changed

+176
-1
lines changed

‎articles/azure-arc/servers/run-command.md

Lines changed: 176 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
---
22
title: How to remotely and securely configure servers using Run command (Preview)
33
description: Learn how to remotely and securely configure servers using Run Command.
4-
ms.date: 12/22/2023
4+
ms.date: 02/07/2024
55
ms.topic: conceptual
66
---
77

@@ -22,6 +22,181 @@ Run Command on Azure Arc-enabled servers (Public Preview) uses the Connected Mac
2222
- **Configuration:** Run Command doesn't require more configuration or the deployment of any extensions. The
2323
Connected Machine agent version must be 1.33 or higher.
2424

25+
26+
## Limiting access to Run Command using RBAC
27+
28+
Listing the run commands or showing details of a command requires the `Microsoft.HybridCompute/machines/runCommands/read` permission. The built-in [Reader](/azure/role-based-access-control/built-in-roles) role and higher levels have this permission.
29+
30+
Running a command requires the `Microsoft.HybridCompute/machines/runCommands/write` permission. The [Azure Connected Machine Resource Administrator](/azure/role-based-access-control/built-in-roles) role and higher levels have this permission.
31+
32+
You can use one of the [built-in roles](/azure/role-based-access-control/built-in-roles) or create a [custom role](/azure/role-based-access-control/custom-roles) to use Run Command.
33+
34+
## Blocking run commands locally
35+
36+
The Connected Machine agent supports local configurations that allow you to set an allowlist or a blocklist. See [Extension allowlists and blocklists](security-overview.md#extension-allowlists-and-blocklists) to learn more.
37+
38+
For Windows:
39+
40+
`azcmagent config set extensions.blocklist " microsoft.cplat.core/runcommandhandlerwindows"`
41+
42+
For Linux:
43+
44+
`azcmagent config set extensions.blocklist " microsoft.cplat.core/runcommandhandlerlinux"`
45+
46+
47+
## Azure CLI
48+
49+
The following examples use [az connectedmachine run-command](/cli/azure/connectedmachine/run-command) to run a shell script on an Azure Windows machine.
50+
51+
### Execute a script with the machine
52+
53+
This command delivers the script to the machine, executes it, and returns the captured output.
54+
55+
```azurecli
56+
az connectedmachine run-command create –-name "myRunCommand" --machine-name "myMachine" --resource-group "myRG" --script "Write-Host Hello World!"
57+
```
58+
59+
### List all deployed RunCommand resources on a machine
60+
61+
This command returns a full list of previously deployed run commands along with their properties.
62+
63+
```azurecli
64+
az connectedmachine run-command list --machine-name "myMachine" --resource-group "myRG"
65+
```
66+
67+
### Get execution status and results
68+
69+
This command retrieves current execution progress, including latest output, start/end time, exit code, and terminal state of the execution.
70+
71+
```azurecli
72+
az connectedmachine run-command show --name "myRunCommand" --machine-name "myMachine" --resource-group "myRG"
73+
```
74+
75+
> [!NOTE]
76+
> Output and error fields in `instanceView` is limited to the last 4KB. To access the full output and error, you can forward the output and error data to storage append blobs using `-outputBlobUri` and `-errorBlobUri` parameters while executing Run Command.
77+
>
78+
79+
### Delete RunCommand resource from the machine
80+
81+
Remove the RunCommand resource previously deployed on the machine. If the script execution is still in progress, execution will be terminated.
82+
83+
```azurecli
84+
az connectedmachine run-command delete --name "myRunCommand" --machine-name "myMachine" --resource-group "myRG"
85+
```
86+
87+
## PowerShell
88+
89+
### Execute a script with the machine
90+
91+
```powershell
92+
New-AzConnectedMachineRunCommand -ResourceGroupName "myRG" -MachineName "myMachine" -Location "EastUS" -RunCommandName "RunCommandName" –SourceScript "echo Hello World!"
93+
```
94+
95+
### Execute a script on the machine using SourceScriptUri parameter
96+
97+
`OutputBlobUri` and `ErrorBlobUri` are optional parameters.
98+
99+
```powershell
100+
New-AzConnectedMachineRunCommand -ResourceGroupName -MachineName -RunCommandName -SourceScriptUri “< SAS URI of a storage blob with read access or public URI>” -OutputBlobUri “< SAS URI of a storage append blob with read, add, create, write access>” -ErrorBlobUri “< SAS URI of a storage append blob with read, add, create, write access>”
101+
```
102+
103+
### List all deployed RunCommand resources on a machine
104+
105+
This command returns a full list of previously deployed Run Commands along with their properties.
106+
107+
```powershell
108+
Get-AzConnectedMachineRunCommand -ResourceGroupName "myRG" -MachineName "myMachine"
109+
```
110+
111+
### Get execution status and results
112+
113+
This command retrieves current execution progress, including latest output, start/end time, exit code, and terminal state of the execution.
114+
115+
```powershell
116+
Get-AzConnectedMachineRunCommand -ResourceGroupName "myRG" - MachineName "myMachine" -RunCommandName "RunCommandName"
117+
```
118+
119+
### Create or update Run Command on a machine using SourceScriptUri (storage blob SAS URL)
120+
121+
Create or update Run Command on a Windows machine using a SAS URL of a storage blob that contains a PowerShell script. `SourceScriptUri` can be a storage blob’s full SAS URL or public URL.
122+
123+
```powershell
124+
New-AzConnectedMachineRunCommand -ResourceGroupName MyRG0 -MachineName MyMachine -RunCommandName MyRunCommand -Location EastUS2EUAP -SourceScriptUri <SourceScriptUri>
125+
```
126+
127+
> [!NOTE]
128+
> SAS URL must provide read access to the blob. An expiration time of 24 hours is suggested for SAS URL. SAS URLs can be generated on the Azure portal using blob options, or SAS token using `New-AzStorageBlobSASToken`. If generating SAS token using `New-AzStorageBlobSASToken`, your SAS URL = "base blob URL" + "?" + "SAS token from `New-AzStorageBlobSASToken`"
129+
>
130+
131+
### Get a Run Command Instance View for a machine after creating or updating Run Command
132+
133+
Get a Run Command for machine with Instance View. Instance View contains the execution state of run command (Succeeded, Failed, etc.), exit code, standard output, and standard error generated by executing the script using Run Command. A non-zero ExitCode indicates an unsuccessful execution.
134+
135+
```powershell
136+
Get-AzConnectedMachineRunCommand -ResourceGroupName MyRG -MachineName MyMachine -RunCommandName MyRunCommand
137+
```
138+
139+
`InstanceViewExecutionState`: Status of user's Run Command script. Refer to this state to know whether your script was successful or not.
140+
141+
`ProvisioningState`: Status of general extension provisioning end to end (whether extension platform was able to trigger Run Command script or not).
142+
143+
### Create or update Run Command on a machine using SourceScript (script text)
144+
145+
Create or update Run Command on a machine passing the script content directly to `-SourceScript` parameter. Use `;` to separate multiple commands.
146+
147+
```powershell
148+
New-AzConnectedMachineRunCommand -ResourceGroupName MyRG0 -MachineName MyMachine -RunCommandName MyRunCommand2 -Location EastUS2EUAP -SourceScript "id; echo HelloWorld"
149+
```
150+
151+
### Create or update Run Command on a machine using OutputBlobUri, ErrorBlobUri to stream standard output and standard error messages to output and error Append blobs
152+
153+
Create or update Run Command on a machine and stream standard output and standard error messages to output and error Append blobs.
154+
155+
```powershell
156+
New-AzConnectedMachineRunCommand -ResourceGroupName MyRG0 - MachineName MyMachine -RunCommandName MyRunCommand3 -Location EastUS2EUAP -SourceScript "id; echo HelloWorld"-OutputBlobUri <OutPutBlobUrI> -ErrorBlobUri <ErrorBlobUri>
157+
```
158+
159+
> [!NOTE]
160+
> Output and error blobs must be the AppendBlob type and their SAS URLs must provide read, append, create, write access to the blob. An expiration time of 24 hours is suggested for SAS URL. If output or error blob does not exist, a blob of type AppendBlob will be created. SAS URLs can be generated on Azure portal using blob's options, or SAS token from using `New-AzStorageBlobSASToken`.
161+
>
162+
163+
### Create or update Run Command on a machine as a different user using RunAsUser and RunAsPassword parameters
164+
165+
Create or update Run Command on a machine as a different user using `RunAsUser` and `RunAsPassword` parameters. For RunAs to work properly, contact the administrator the of machine and make sure user is added on the machine, user has access to resources accessed by the Run Command (directories, files, network etc.), and in case of Windows machine, 'Secondary Logon' service is running on the machine.
166+
167+
```powershell
168+
New-AzMachineRunCommand -ResourceGroupName MyRG0 -MachineName MyMachine -RunCommandName MyRunCommand -Location EastUS2EUAP -SourceScript "id; echo HelloWorld" -RunAsUser myusername -RunAsPassword mypassword
169+
```
170+
171+
### Create or update Run Command on a machine resource using SourceScriptUri (storage blob SAS URL)
172+
173+
Create or update Run Command on a Windows machine resource using a SAS URL of a storage blob that contains a PowerShell script.
174+
175+
176+
```powershell
177+
New-AzMachineRunCommand -ResourceGroupName MyRG0 -MachineName MyMachine -RunCommandName MyRunCommand -Location EastUS2EUAP -SourceScriptUri <SourceScriptUri>
178+
```
179+
180+
> [!NOTE]
181+
> SAS URL must provide read access to the blob. An expiry time of 24 hours is suggested for SAS URL. SAS URLs can be generated on Azure portal using blob options or SAS token using `New-AzStorageBlobSASToken`. If generating SAS token using `New-AzStorageBlobSASToken`, the SAS URL format is: base blob URL + "?" + the SAS token from `New-AzStorageBlobSASToken`.
182+
>
183+
184+
### Create or update Run Command on a machine instance using Parameter and ProtectedParameter parameters (Public and Protected Parameters to script)
185+
186+
Use ProtectedParameter to pass any sensitive inputs to script such as passwords, keys etc.
187+
188+
- Windows: Parameters and ProtectedParameters are passed to script as arguments are passed to script and run like this: `myscript.ps1 -publicParam1 publicParam1value -publicParam2 publicParam2value -secret1 secret1value -secret2 secret2value`
189+
190+
- Linux: Named Parameters and its values are set to environment config, which should be accessible within the .sh script. For Nameless arguments, pass an empty string to name input. Nameless arguments are passed to script and run like this: `myscript.sh publicParam1value publicParam2value secret1value secret2value`
191+
192+
### Delete RunCommand resource from the machine
193+
194+
Remove the RunCommand resource previously deployed on the machine. If the script execution is still in progress, execution will be terminated.
195+
196+
```powershell
197+
Remove-AzConnetedMachineRunCommand -ResourceGroupName "myRG" -MachineName "myMachine" -RunCommandName "RunCommandName"
198+
```
199+
25200
## Run Command operations
26201

27202
Run Command on Azure Arc-enabled servers supports the following operations:

0 commit comments

Comments
 (0)