Skip to content

Commit fcd8d69

Browse files
GijsreynGijsreyn
committed
Update with latest changes
1 parent 2c79334 commit fcd8d69

File tree

2 files changed

+134
-90
lines changed

2 files changed

+134
-90
lines changed

‎docs/reference/resources/Microsoft/OpenSSH/SSHD/Windows/examples/configure-default-shell-powershell.md

Lines changed: 99 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,99 @@
1+
---
2+
description: >
3+
Example showing how to use Microsoft.OpenSSH.SSHD/Windows to configure the default shell for SSH sessions.
4+
ms.date: 07/15/2025
5+
ms.topic: reference
6+
title: Configure default shell for SSH
7+
---
8+
9+
# Configure default shell for SSH
10+
11+
This example demonstrates how to use the `Microsoft.OpenSSH.SSHD/Windows` resource to
12+
set the default shell for SSH connections. The examples below configure PowerShell
13+
as the default shell for all SSH sessions.
14+
15+
> [!NOTE]
16+
> You should run this example in an elevated context (as Administrator) to
17+
> ensure the SSH server configuration can be updated successfully.
18+
19+
## Test the current default shell
20+
21+
The following snippet shows how you can use the resource with the [dsc resource test][00] command to check whether PowerShell is set as the default shell.
22+
23+
```powershell
24+
$instance = @{
25+
shell = 'C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe'
26+
} | ConvertTo-Json
27+
28+
dsc resource test --resource Microsoft.OpenSSH.SSHD/Windows --input $instance
29+
```
30+
31+
When PowerShell is not set as the default shell, DSC returns the following result:
32+
33+
```yaml
34+
desiredState:
35+
shell: C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe
36+
actualState: {}
37+
inDesiredState: false
38+
differingProperties:
39+
- shell
40+
```
41+
42+
## Set PowerShell as the default shell
43+
44+
To set PowerShell as the default shell for SSH, use the [dsc resource set][01] command.
45+
46+
```powershell
47+
dsc resource set --resource Microsoft.OpenSSH.SSHD/Windows --input $instance
48+
```
49+
50+
When the resource updates the default shell, DSC returns the following result:
51+
52+
```yaml
53+
beforeState: {}
54+
afterState:
55+
shell: C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe
56+
changedProperties:
57+
- shell
58+
```
59+
60+
You can test the instance again to confirm that PowerShell is now the default shell:
61+
62+
```powershell
63+
dsc resource test --resource Microsoft.OpenSSH.SSHD/Windows --input $instance
64+
```
65+
66+
```yaml
67+
desiredState:
68+
shell: C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe
69+
actualState:
70+
shell: C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe
71+
inDesiredState: true
72+
differingProperties: []
73+
```
74+
75+
## Cleanup
76+
77+
To restore your system to its original state, use the following command to delete the registry key:
78+
79+
```powershell
80+
$params = @{
81+
Path = 'HKLM:\SOFTWARE\OpenSSH'
82+
Name = 'DefaultShell'
83+
}
84+
Remove-ItemProperty @params
85+
```
86+
87+
To verify the configuration is removed, use the `dsc resource get` command:
88+
89+
```powershell
90+
dsc resource get --resource Microsoft.OpenSSH.SSHD/Windows --input $instance
91+
```
92+
93+
```yaml
94+
actualState: {}
95+
```
96+
97+
<!-- Link reference definitions -->
98+
[00]: ../../../../../cli/resource/test.md
99+
[01]: ../../../../../cli/resource/set.md

‎docs/reference/resources/Microsoft/OpenSSH/SSHD/Windows/index.md

Lines changed: 35 additions & 90 deletions
Original file line numberDiff line numberDiff line change
@@ -27,10 +27,10 @@ resources:
2727
- name: <instance name>
2828
type: Microsoft.OpenSSH.SSHD/Windows
2929
properties:
30-
# Required properties
3130
# Instance properties
32-
_exist:
33-
# Add other properties as needed
31+
shell:
32+
escapeArguments:
33+
cmdOption:
3434
```
3535
3636
## Description
@@ -60,7 +60,6 @@ The resource has the following capabilities:
6060

6161
- `get` - You can use the resource to retrieve the actual state of an instance.
6262
- `set` - You can use the resource to enforce the desired state for an instance.
63-
- `export` - You can use the resource to export the SSHD configuration of existing instances.
6463

6564
This resource uses the synthetic test functionality of DSC to determine whether an instance is in
6665
the desired state. For more information about resource capabilities, see
@@ -70,41 +69,27 @@ the desired state. For more information about resource capabilities, see
7069

7170
<!-- Example definitions would need to be created as separate files -->
7271

73-
1. [Configure default shell PowerShell][03] - Shows how to set the default shell to PowerShell.exe
72+
1. [Configure default shell PowerShell][01] - Shows how to set the default shell to PowerShell.exe
7473

7574
## Properties
7675

7776
The following list describes the properties for the resource.
7877

79-
- **Required properties:** <a id="required-properties"></a> The following properties are always
80-
required when defining an instance of the resource. An instance that doesn't define each of these
81-
properties is invalid. For more information, see the "Required resource properties" section in
82-
[DSC resource properties][01]
83-
84-
- [shell](#shell) - The path to the default shell for SSH.
85-
86-
- **Key properties:** <a id="key-properties"> The following properties uniquely identify an
87-
instance. If two instances of a resource have the same values for their key properties, the
88-
instances are conflicting. For more information about key properties, see the "Key resource
89-
properties" section in [DSC resource properties][02].
90-
91-
- [shell](#shell) (required) - The path to the default shell for SSH.
92-
9378
- **Instance properties:** <a id="instance-properties"></a> The following properties are optional.
9479
They define the desired state for an instance of the resource.
9580

96-
- [cmd_option](#cmd_option) - Specifies command-line options for the shell.
97-
- [escape_arguments](#escape_arguments) - Specifies whether shell arguments should be escaped.
98-
- [shell_arguments](#shell_arguments) - Specifies the arguments to pass to the shell.
81+
- [shell](#shell) - The path to the default shell for SSH.
82+
- [cmdOption](#cmdOption) - Specifies command-line options for the shell.
83+
- [escapeArguments](#escapeArguments) - Specifies whether shell arguments should be escaped.
9984

10085
### shell
10186

10287
<details><summary>Expand for <code>shell</code> property metadata</summary>
10388

10489
```yaml
105-
Type : string
106-
IsRequired : true
107-
IsKey : true
90+
Type : string, null
91+
IsRequired : false
92+
IsKey : false
10893
IsReadOnly : false
10994
IsWriteOnly : false
11095
```
@@ -114,12 +99,12 @@ IsWriteOnly : false
11499
Defines the path to the default shell executable to use for SSH sessions.
115100
This property is required and must specify a valid path to an executable on the system.
116101

117-
### cmd_option
102+
### cmdOption
118103

119-
<details><summary>Expand for <code>cmd_option</code> property metadata</summary>
104+
<details><summary>Expand for <code>cmdOption</code> property metadata</summary>
120105

121106
```yaml
122-
Type : string
107+
Type : string, null
123108
IsRequired : false
124109
IsKey : false
125110
IsReadOnly : false
@@ -130,12 +115,12 @@ IsWriteOnly : false
130115

131116
Specifies optional command-line options to pass to the shell when it's launched.
132117

133-
### escape_arguments
118+
### escapeArguments
134119

135-
<details><summary>Expand for <code>escape_arguments</code> property metadata</summary>
120+
<details><summary>Expand for <code>escapeArguments</code> property metadata</summary>
136121

137122
```yaml
138-
Type : boolean
123+
Type : boolean, null
139124
IsRequired : false
140125
IsKey : false
141126
IsReadOnly : false
@@ -147,26 +132,6 @@ IsWriteOnly : false
147132
Determines whether shell arguments should be escaped. When set to `true`, the arguments provided
148133
in `shell_arguments` will be properly escaped before being passed to the shell.
149134

150-
### shell_arguments
151-
152-
<details><summary>Expand for <code>shell_arguments</code> property metadata</summary>
153-
154-
```yaml
155-
Type : array
156-
ItemsType : string
157-
ItemsMustBeUnique : false
158-
ItemsMinimumCount : 0
159-
IsRequired : false
160-
IsKey : false
161-
IsReadOnly : false
162-
IsWriteOnly : false
163-
```
164-
165-
</details>
166-
167-
Specifies an array of arguments to pass to the shell when it's launched.
168-
Each element in the array represents a separate argument.
169-
170135
## Instance validating schema
171136

172137
The following snippet contains the JSON Schema that validates an instance of the resource. The
@@ -176,23 +141,24 @@ non validating keywords are omitted.
176141
```json
177142
{
178143
"type": "object",
179-
"required": ["shell"],
180-
"additionalProperties": false,
181144
"properties": {
182145
"shell": {
183-
"type": "string"
184-
},
185-
"cmd_option": {
186-
"type": "string"
146+
"type": [
147+
"string",
148+
"null"
149+
]
187150
},
188-
"escape_arguments": {
189-
"type": "boolean"
151+
"cmdOption": {
152+
"type": [
153+
"string",
154+
"null"
155+
]
190156
},
191-
"shell_arguments": {
192-
"type": "array",
193-
"items": {
194-
"type": "string"
195-
}
157+
"escapeArguments": {
158+
"type": [
159+
"boolean",
160+
"null"
161+
]
196162
}
197163
}
198164
}
@@ -204,9 +170,6 @@ The resource returns the following exit codes from operations:
204170

205171
- [0](#exit-code-0) - Success
206172
- [1](#exit-code-1) - Invalid parameter
207-
- [2](#exit-code-2) - Invalid input
208-
- [3](#exit-code-3) - SSH configuration error
209-
- [4](#exit-code-4) - Json serialization failed
210173

211174
### Exit code 0
212175

@@ -217,31 +180,13 @@ Indicates the resource operation completed without errors.
217180
Indicates the resource operation failed due to an invalid parameter. When the resource returns this
218181
exit code, it also emits an error message with details about the invalid parameter.
219182

220-
### Exit code 2
221-
222-
Indicates the resource operation failed because the input instance was invalid. When the resource
223-
returns this exit code, it also emits one or more error messages with details describing how the
224-
input instance was invalid.
225-
226-
### Exit code 3
227-
228-
Indicates the resource operation failed due to an error in the SSH server configuration. When the
229-
resource returns this exit code, it also emits the error message related to the SSH configuration issue.
230-
231-
### Exit code 4
232-
233-
Indicates the resource operation failed because the result couldn't be serialized to JSON.
234-
235183
## See also
236184

237-
- [Microsoft.DSC/PowerShell resource][03]
238-
- For more information about OpenSSH, see [OpenSSH Documentation][04]
185+
- [Microsoft.DSC/PowerShell resource][02]
186+
- For more information about OpenSSH, see [OpenSSH Documentation][03]
239187

240188
<!-- Link definitions -->
241189
[00]: ../../../../../concepts/resources/capabilities.md
242-
[01]: ../../../../../concepts/resources/properties.md#required-resource-properties
243-
[02]: ../../../../../concepts/resources/properties.md#key-resource-properties
244-
[03]: ../../../DSC/PowerShell/index.md
245-
[04]: /windowsserverdocs/WindowsServerDocs/administration/OpenSSH/openssh-overview
246-
[05]: ./examples/configure-default-shell-powershell.md
247-
190+
[01]: ./examples/configure-default-shell-powershell.md
191+
[02]: ../../../DSC/PowerShell/index.md
192+
[03]: /windowsserverdocs/WindowsServerDocs/administration/OpenSSH/openssh-overview

0 commit comments

Comments
 (0)