From 7b2cb703379f8e4a2480420c7cf0fb805f7c705e Mon Sep 17 00:00:00 2001 From: GijsR Date: Wed, 2 Jul 2025 14:01:21 +0200 Subject: [PATCH 1/3] Initial reference documentation for Microsoft.OpenSSH.SSHD/Windows --- .../configure-default-shell-powershell.md | 0 .../Microsoft/OpenSSH/SSHD/Windows/index.md | 247 ++++++++++++++++++ 2 files changed, 247 insertions(+) create mode 100644 docs/reference/resources/Microsoft/OpenSSH/SSHD/Windows/examples/configure-default-shell-powershell.md create mode 100644 docs/reference/resources/Microsoft/OpenSSH/SSHD/Windows/index.md diff --git a/docs/reference/resources/Microsoft/OpenSSH/SSHD/Windows/examples/configure-default-shell-powershell.md b/docs/reference/resources/Microsoft/OpenSSH/SSHD/Windows/examples/configure-default-shell-powershell.md new file mode 100644 index 000000000..e69de29bb diff --git a/docs/reference/resources/Microsoft/OpenSSH/SSHD/Windows/index.md b/docs/reference/resources/Microsoft/OpenSSH/SSHD/Windows/index.md new file mode 100644 index 000000000..edc3f93bd --- /dev/null +++ b/docs/reference/resources/Microsoft/OpenSSH/SSHD/Windows/index.md @@ -0,0 +1,247 @@ +--- +description: Microsoft.OpenSSH.SSHD/Windows resource reference documentation +ms.date: 07/02/2025 +ms.topic: reference +title: Microsoft.OpenSSH.SSHD/Windows +--- + +# Microsoft.OpenSSH.SSHD/Windows + +## Synopsis + +Manage SSH client and server configuration. + +## Metadata + +```yaml +Version : 0.1.0 +Kind : resource +Tags : [Windows] +Author : Microsoft +``` + +## Instance definition syntax + +```yaml +resources: + - name: + type: Microsoft.OpenSSH.SSHD/Windows + properties: + # Required properties + # Instance properties + _exist: + # Add other properties as needed +``` + +## Description + +The `Microsoft.OpenSSH.SSHD/Windows` resource enables you to idempotently manage SSH server +configuration. The resource can: + +- Add, update, and remove SSH client and server configuration settings. + +> [!NOTE] +> This resource is installed with DSC itself on systems. +> +> You can update this resource by updating DSC. When you update DSC, the updated version of this +> resource is automatically available. + +## Requirements + +- The resource requires OpenSSH server and client to be installed on the Windows system. +- The resource must run in a process context that has permissions to manage the SSH server + configuration settings. +- The resource must run at least under a Windows Server 2019 or Windows 10 (build 1809) + operating system. + +## Capabilities + +The resource has the following capabilities: + +- `get` - You can use the resource to retrieve the actual state of an instance. +- `set` - You can use the resource to enforce the desired state for an instance. +- `export` - You can use the resource to export the SSHD configuration of existing instances. + +This resource uses the synthetic test functionality of DSC to determine whether an instance is in +the desired state. For more information about resource capabilities, see +[DSC resource capabilities][00]. + +## Examples + + + +1. [Configure default shell PowerShell][03] - Shows how to set the default shell to PowerShell.exe + +## Properties + +The following list describes the properties for the resource. + +- **Required properties:** The following properties are always + required when defining an instance of the resource. An instance that doesn't define each of these + properties is invalid. For more information, see the "Required resource properties" section in + [DSC resource properties][01] + + - [shell](#shell) - The path to the default shell for SSH. + +- **Key properties:** The following properties uniquely identify an + instance. If two instances of a resource have the same values for their key properties, the + instances are conflicting. For more information about key properties, see the "Key resource + properties" section in [DSC resource properties][02]. + + - [shell](#shell) (required) - The path to the default shell for SSH. + +- **Instance properties:** The following properties are optional. + They define the desired state for an instance of the resource. + + - [cmd_option](#cmd_option) - Specifies command-line options for the shell. + - [escape_arguments](#escape_arguments) - Specifies whether shell arguments should be escaped. + - [shell_arguments](#shell_arguments) - Specifies the arguments to pass to the shell. + +### shell + +
Expand for shell property metadata + +```yaml +Type : string +IsRequired : true +IsKey : true +IsReadOnly : false +IsWriteOnly : false +``` + +
+ +Defines the path to the default shell executable to use for SSH sessions. +This property is required and must specify a valid path to an executable on the system. + +### cmd_option + +
Expand for cmd_option property metadata + +```yaml +Type : string +IsRequired : false +IsKey : false +IsReadOnly : false +IsWriteOnly : false +``` + +
+ +Specifies optional command-line options to pass to the shell when it's launched. + +### escape_arguments + +
Expand for escape_arguments property metadata + +```yaml +Type : boolean +IsRequired : false +IsKey : false +IsReadOnly : false +IsWriteOnly : false +``` + +
+ +Determines whether shell arguments should be escaped. When set to `true`, the arguments provided +in `shell_arguments` will be properly escaped before being passed to the shell. + +### shell_arguments + +
Expand for shell_arguments property metadata + +```yaml +Type : array +ItemsType : string +ItemsMustBeUnique : false +ItemsMinimumCount : 0 +IsRequired : false +IsKey : false +IsReadOnly : false +IsWriteOnly : false +``` + +
+ +Specifies an array of arguments to pass to the shell when it's launched. +Each element in the array represents a separate argument. + +## Instance validating schema + +The following snippet contains the JSON Schema that validates an instance of the resource. The +validating schema only includes schema keywords that affect how the instance is validated. All +non validating keywords are omitted. + +```json +{ + "type": "object", + "required": ["shell"], + "additionalProperties": false, + "properties": { + "shell": { + "type": "string" + }, + "cmd_option": { + "type": "string" + }, + "escape_arguments": { + "type": "boolean" + }, + "shell_arguments": { + "type": "array", + "items": { + "type": "string" + } + } + } +} +``` + +## Exit codes + +The resource returns the following exit codes from operations: + +- [0](#exit-code-0) - Success +- [1](#exit-code-1) - Invalid parameter +- [2](#exit-code-2) - Invalid input +- [3](#exit-code-3) - SSH configuration error +- [4](#exit-code-4) - Json serialization failed + +### Exit code 0 + +Indicates the resource operation completed without errors. + +### Exit code 1 + +Indicates the resource operation failed due to an invalid parameter. When the resource returns this +exit code, it also emits an error message with details about the invalid parameter. + +### Exit code 2 + +Indicates the resource operation failed because the input instance was invalid. When the resource +returns this exit code, it also emits one or more error messages with details describing how the +input instance was invalid. + +### Exit code 3 + +Indicates the resource operation failed due to an error in the SSH server configuration. When the +resource returns this exit code, it also emits the error message related to the SSH configuration issue. + +### Exit code 4 + +Indicates the resource operation failed because the result couldn't be serialized to JSON. + +## See also + +- [Microsoft.DSC/PowerShell resource][03] +- For more information about OpenSSH, see [OpenSSH Documentation][04] + + +[00]: ../../../../../concepts/resources/capabilities.md +[01]: ../../../../../concepts/resources/properties.md#required-resource-properties +[02]: ../../../../../concepts/resources/properties.md#key-resource-properties +[03]: ../../../DSC/PowerShell/index.md +[04]: /windowsserverdocs/WindowsServerDocs/administration/OpenSSH/openssh-overview +[05]: ./examples/configure-default-shell-powershell.md + From 97e5eb1bd7d6c4ad66c8d8b147feebdf7b110abb Mon Sep 17 00:00:00 2001 From: GijsR Date: Tue, 15 Jul 2025 07:10:03 +0200 Subject: [PATCH 2/3] Update with latest changes --- .../configure-default-shell-powershell.md | 99 ++++++++++++++ .../Microsoft/OpenSSH/SSHD/Windows/index.md | 125 +++++------------- 2 files changed, 134 insertions(+), 90 deletions(-) diff --git a/docs/reference/resources/Microsoft/OpenSSH/SSHD/Windows/examples/configure-default-shell-powershell.md b/docs/reference/resources/Microsoft/OpenSSH/SSHD/Windows/examples/configure-default-shell-powershell.md index e69de29bb..321e84b1e 100644 --- a/docs/reference/resources/Microsoft/OpenSSH/SSHD/Windows/examples/configure-default-shell-powershell.md +++ b/docs/reference/resources/Microsoft/OpenSSH/SSHD/Windows/examples/configure-default-shell-powershell.md @@ -0,0 +1,99 @@ +--- +description: > + Example showing how to use Microsoft.OpenSSH.SSHD/Windows to configure the default shell for SSH sessions. +ms.date: 07/15/2025 +ms.topic: reference +title: Configure default shell for SSH +--- + +# Configure default shell for SSH + +This example demonstrates how to use the `Microsoft.OpenSSH.SSHD/Windows` resource to +set the default shell for SSH connections. The examples below configure PowerShell +as the default shell for all SSH sessions. + +> [!NOTE] +> You should run this example in an elevated context (as Administrator) to +> ensure the SSH server configuration can be updated successfully. + +## Test the current default shell + +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. + +```powershell +$instance = @{ + shell = 'C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe' +} | ConvertTo-Json + +dsc resource test --resource Microsoft.OpenSSH.SSHD/Windows --input $instance +``` + +When PowerShell is not set as the default shell, DSC returns the following result: + +```yaml +desiredState: + shell: C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe +actualState: {} +inDesiredState: false +differingProperties: +- shell +``` + +## Set PowerShell as the default shell + +To set PowerShell as the default shell for SSH, use the [dsc resource set][01] command. + +```powershell +dsc resource set --resource Microsoft.OpenSSH.SSHD/Windows --input $instance +``` + +When the resource updates the default shell, DSC returns the following result: + +```yaml +beforeState: {} +afterState: + shell: C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe +changedProperties: +- shell +``` + +You can test the instance again to confirm that PowerShell is now the default shell: + +```powershell +dsc resource test --resource Microsoft.OpenSSH.SSHD/Windows --input $instance +``` + +```yaml +desiredState: + shell: C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe +actualState: + shell: C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe +inDesiredState: true +differingProperties: [] +``` + +## Cleanup + +To restore your system to its original state, use the following command to delete the registry key: + +```powershell +$params = @{ + Path = 'HKLM:\SOFTWARE\OpenSSH' + Name = 'DefaultShell' +} +Remove-ItemProperty @params +``` + +To verify the configuration is removed, use the `dsc resource get` command: + +```powershell +dsc resource get --resource Microsoft.OpenSSH.SSHD/Windows --input $instance +``` + +```yaml +actualState: {} +``` + + +[00]: ../../../../../cli/resource/test.md +[01]: ../../../../../cli/resource/set.md diff --git a/docs/reference/resources/Microsoft/OpenSSH/SSHD/Windows/index.md b/docs/reference/resources/Microsoft/OpenSSH/SSHD/Windows/index.md index edc3f93bd..16212fcd0 100644 --- a/docs/reference/resources/Microsoft/OpenSSH/SSHD/Windows/index.md +++ b/docs/reference/resources/Microsoft/OpenSSH/SSHD/Windows/index.md @@ -27,10 +27,10 @@ resources: - name: type: Microsoft.OpenSSH.SSHD/Windows properties: - # Required properties # Instance properties - _exist: - # Add other properties as needed + shell: + escapeArguments: + cmdOption: ``` ## Description @@ -60,7 +60,6 @@ The resource has the following capabilities: - `get` - You can use the resource to retrieve the actual state of an instance. - `set` - You can use the resource to enforce the desired state for an instance. -- `export` - You can use the resource to export the SSHD configuration of existing instances. This resource uses the synthetic test functionality of DSC to determine whether an instance is in the desired state. For more information about resource capabilities, see @@ -70,41 +69,27 @@ the desired state. For more information about resource capabilities, see -1. [Configure default shell PowerShell][03] - Shows how to set the default shell to PowerShell.exe +1. [Configure default shell PowerShell][01] - Shows how to set the default shell to PowerShell.exe ## Properties The following list describes the properties for the resource. -- **Required properties:** The following properties are always - required when defining an instance of the resource. An instance that doesn't define each of these - properties is invalid. For more information, see the "Required resource properties" section in - [DSC resource properties][01] - - - [shell](#shell) - The path to the default shell for SSH. - -- **Key properties:** The following properties uniquely identify an - instance. If two instances of a resource have the same values for their key properties, the - instances are conflicting. For more information about key properties, see the "Key resource - properties" section in [DSC resource properties][02]. - - - [shell](#shell) (required) - The path to the default shell for SSH. - - **Instance properties:** The following properties are optional. They define the desired state for an instance of the resource. - - [cmd_option](#cmd_option) - Specifies command-line options for the shell. - - [escape_arguments](#escape_arguments) - Specifies whether shell arguments should be escaped. - - [shell_arguments](#shell_arguments) - Specifies the arguments to pass to the shell. + - [shell](#shell) - The path to the default shell for SSH. + - [cmdOption](#cmdOption) - Specifies command-line options for the shell. + - [escapeArguments](#escapeArguments) - Specifies whether shell arguments should be escaped. ### shell
Expand for shell property metadata ```yaml -Type : string -IsRequired : true -IsKey : true +Type : string, null +IsRequired : false +IsKey : false IsReadOnly : false IsWriteOnly : false ``` @@ -114,12 +99,12 @@ IsWriteOnly : false Defines the path to the default shell executable to use for SSH sessions. This property is required and must specify a valid path to an executable on the system. -### cmd_option +### cmdOption -
Expand for cmd_option property metadata +
Expand for cmdOption property metadata ```yaml -Type : string +Type : string, null IsRequired : false IsKey : false IsReadOnly : false @@ -130,12 +115,12 @@ IsWriteOnly : false Specifies optional command-line options to pass to the shell when it's launched. -### escape_arguments +### escapeArguments -
Expand for escape_arguments property metadata +
Expand for escapeArguments property metadata ```yaml -Type : boolean +Type : boolean, null IsRequired : false IsKey : false IsReadOnly : false @@ -147,26 +132,6 @@ IsWriteOnly : false Determines whether shell arguments should be escaped. When set to `true`, the arguments provided in `shell_arguments` will be properly escaped before being passed to the shell. -### shell_arguments - -
Expand for shell_arguments property metadata - -```yaml -Type : array -ItemsType : string -ItemsMustBeUnique : false -ItemsMinimumCount : 0 -IsRequired : false -IsKey : false -IsReadOnly : false -IsWriteOnly : false -``` - -
- -Specifies an array of arguments to pass to the shell when it's launched. -Each element in the array represents a separate argument. - ## Instance validating schema The following snippet contains the JSON Schema that validates an instance of the resource. The @@ -176,23 +141,24 @@ non validating keywords are omitted. ```json { "type": "object", - "required": ["shell"], - "additionalProperties": false, "properties": { "shell": { - "type": "string" - }, - "cmd_option": { - "type": "string" + "type": [ + "string", + "null" + ] }, - "escape_arguments": { - "type": "boolean" + "cmdOption": { + "type": [ + "string", + "null" + ] }, - "shell_arguments": { - "type": "array", - "items": { - "type": "string" - } + "escapeArguments": { + "type": [ + "boolean", + "null" + ] } } } @@ -204,9 +170,6 @@ The resource returns the following exit codes from operations: - [0](#exit-code-0) - Success - [1](#exit-code-1) - Invalid parameter -- [2](#exit-code-2) - Invalid input -- [3](#exit-code-3) - SSH configuration error -- [4](#exit-code-4) - Json serialization failed ### Exit code 0 @@ -217,31 +180,13 @@ Indicates the resource operation completed without errors. Indicates the resource operation failed due to an invalid parameter. When the resource returns this exit code, it also emits an error message with details about the invalid parameter. -### Exit code 2 - -Indicates the resource operation failed because the input instance was invalid. When the resource -returns this exit code, it also emits one or more error messages with details describing how the -input instance was invalid. - -### Exit code 3 - -Indicates the resource operation failed due to an error in the SSH server configuration. When the -resource returns this exit code, it also emits the error message related to the SSH configuration issue. - -### Exit code 4 - -Indicates the resource operation failed because the result couldn't be serialized to JSON. - ## See also -- [Microsoft.DSC/PowerShell resource][03] -- For more information about OpenSSH, see [OpenSSH Documentation][04] +- [Microsoft.DSC/PowerShell resource][02] +- For more information about OpenSSH, see [OpenSSH Documentation][03] [00]: ../../../../../concepts/resources/capabilities.md -[01]: ../../../../../concepts/resources/properties.md#required-resource-properties -[02]: ../../../../../concepts/resources/properties.md#key-resource-properties -[03]: ../../../DSC/PowerShell/index.md -[04]: /windowsserverdocs/WindowsServerDocs/administration/OpenSSH/openssh-overview -[05]: ./examples/configure-default-shell-powershell.md - +[01]: ./examples/configure-default-shell-powershell.md +[02]: ../../../DSC/PowerShell/index.md +[03]: /windowsserverdocs/WindowsServerDocs/administration/OpenSSH/openssh-overview From 3509e6b8801f8bbced54dc300c2332943422d900 Mon Sep 17 00:00:00 2001 From: GijsR Date: Tue, 15 Jul 2025 09:59:24 +0200 Subject: [PATCH 3/3] Add sshd_config --- .../Microsoft/OpenSSH/SSHD/Windows/index.md | 6 +- .../examples/export-openssh-configuration.md | 0 .../OpenSSH/SSHD/sshd_config/index.md | 142 ++++++++++++++++++ 3 files changed, 144 insertions(+), 4 deletions(-) create mode 100644 docs/reference/resources/Microsoft/OpenSSH/SSHD/sshd_config/examples/export-openssh-configuration.md create mode 100644 docs/reference/resources/Microsoft/OpenSSH/SSHD/sshd_config/index.md diff --git a/docs/reference/resources/Microsoft/OpenSSH/SSHD/Windows/index.md b/docs/reference/resources/Microsoft/OpenSSH/SSHD/Windows/index.md index 16212fcd0..3049b2712 100644 --- a/docs/reference/resources/Microsoft/OpenSSH/SSHD/Windows/index.md +++ b/docs/reference/resources/Microsoft/OpenSSH/SSHD/Windows/index.md @@ -16,7 +16,7 @@ Manage SSH client and server configuration. ```yaml Version : 0.1.0 Kind : resource -Tags : [Windows] +Tags : [OpenSSH, Windows] Author : Microsoft ``` @@ -38,7 +38,7 @@ resources: The `Microsoft.OpenSSH.SSHD/Windows` resource enables you to idempotently manage SSH server configuration. The resource can: -- Add, update, and remove SSH client and server configuration settings. +- Add and update SSH client and server configuration settings. > [!NOTE] > This resource is installed with DSC itself on systems. @@ -67,8 +67,6 @@ the desired state. For more information about resource capabilities, see ## Examples - - 1. [Configure default shell PowerShell][01] - Shows how to set the default shell to PowerShell.exe ## Properties diff --git a/docs/reference/resources/Microsoft/OpenSSH/SSHD/sshd_config/examples/export-openssh-configuration.md b/docs/reference/resources/Microsoft/OpenSSH/SSHD/sshd_config/examples/export-openssh-configuration.md new file mode 100644 index 000000000..e69de29bb diff --git a/docs/reference/resources/Microsoft/OpenSSH/SSHD/sshd_config/index.md b/docs/reference/resources/Microsoft/OpenSSH/SSHD/sshd_config/index.md new file mode 100644 index 000000000..1bbc48cc8 --- /dev/null +++ b/docs/reference/resources/Microsoft/OpenSSH/SSHD/sshd_config/index.md @@ -0,0 +1,142 @@ +--- +description: Microsoft.OpenSSH.SSHD/sshd_config resource reference documentation +ms.date: 07/15/2025 +ms.topic: reference +title: Microsoft.OpenSSH.SSHD/sshd_config +--- + +# Microsoft.OpenSSH.SSHD/sshd_config + +## Synopsis + +Manage SSH Server Configuration. + +## Metadata + +```yaml +Version : 0.1.0 +Kind : resource +Tags : [OpenSSH, Windows, Linux] +Author : Microsoft +``` + +## Instance definition syntax + +```yaml +resources: + - name: + type: Microsoft.OpenSSH.SSHD/sshd_config + properties: + # Required properties + map: object +``` + +## Description + +The `Microsoft.OpenSSH.SSHD/sshd_config` resource allows you to export client +and server configuration settings. The resource can: + +- Export client and server configuration settings + +> [!NOTE] +> This resource is installed with DSC itself on systems. +> +> You can update this resource by updating DSC. When you update DSC, the updated version of this +> resource is automatically available. + +## Requirements + +- The resource requires OpenSSH server and client to be installed on the Windows system. +- The resource must run at least under a Windows Server 2019 or Windows 10 (build 1809) + operating system. + +## Capabilities + +The resource has the following capabilities: + +- `export` - You can use the resource to export the current SSH server configuration. + +## Examples + +1. [Export OpenSSH configuration][00] - Shows how to export current OpenSSH configuration. + +## Properties + +The following list describes the properties for the resource. + +- **Required properties:** The following properties are always + required when defining an instance of the resource. An instance that doesn't define each of these + properties is invalid. For more information, see the "Required resource properties" section in + [DSC resource properties][01] + + - [map](#map) - + +- **Key properties:** The following properties uniquely identify an + instance. If two instances of a resource have the same values for their key properties, the + instances are conflicting. For more information about key properties, see the "Key resource + properties" section in [DSC resource properties][02]. + + - [map](#map) (required) - + +### map + +
Expand for map property metadata + +```yaml +Type : object +IsRequired : true +IsKey : false +IsReadOnly : false +IsWriteOnly : false +``` + +
+ +## Instance validating schema + +The following snippet contains the JSON Schema that validates an instance of the resource. The +validating schema only includes schema keywords that affect how the instance is validated. All +non validating keywords are omitted. + +```json +{ +"type": "object", + "required": [ + "map" + ], + "properties": { + "map": { + "type": "object", + "additionalProperties": true + } + } +} +``` + +## Exit codes + +The resource returns the following exit codes from operations: + +- [0](#exit-code-0) - Success +- [1](#exit-code-1) - Invalid parameter + +### Exit code 0 + +Indicates the resource operation completed without errors. + +### Exit code 1 + +Indicates the resource operation failed due to an invalid parameter. When the resource returns this +exit code, it also emits an error message with details about the invalid parameter. + +## See also + +- [Microsoft.OpenSSH.SSHD/Windows resource][03] +- For more information about OpenSSH, see [OpenSSH Documentation][04] + + +[00]: examples/export-openssh-configuration.md +[01]: ../../../../../concepts/resources/properties.md#required-resource-properties +[02]: ../../../../../concepts/resources/properties.md#key-resource-properties +[03]: ../Windows/index.md +[04]: /windowsserverdocs/WindowsServerDocs/administration/OpenSSH/openssh-overview