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..321e84b1e --- /dev/null +++ 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 new file mode 100644 index 000000000..3049b2712 --- /dev/null +++ b/docs/reference/resources/Microsoft/OpenSSH/SSHD/Windows/index.md @@ -0,0 +1,190 @@ +--- +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 : [OpenSSH, Windows] +Author : Microsoft +``` + +## Instance definition syntax + +```yaml +resources: + - name: + type: Microsoft.OpenSSH.SSHD/Windows + properties: + # Instance properties + shell: + escapeArguments: + cmdOption: +``` + +## Description + +The `Microsoft.OpenSSH.SSHD/Windows` resource enables you to idempotently manage SSH server +configuration. The resource can: + +- Add and update 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. + +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][01] - Shows how to set the default shell to PowerShell.exe + +## Properties + +The following list describes the properties for the resource. + +- **Instance properties:** The following properties are optional. + They define the desired state for an instance of the resource. + + - [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, null +IsRequired : false +IsKey : false +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. + +### cmdOption + +
Expand for cmdOption property metadata + +```yaml +Type : string, null +IsRequired : false +IsKey : false +IsReadOnly : false +IsWriteOnly : false +``` + +
+ +Specifies optional command-line options to pass to the shell when it's launched. + +### escapeArguments + +
Expand for escapeArguments property metadata + +```yaml +Type : boolean, null +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. + +## 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", + "properties": { + "shell": { + "type": [ + "string", + "null" + ] + }, + "cmdOption": { + "type": [ + "string", + "null" + ] + }, + "escapeArguments": { + "type": [ + "boolean", + "null" + ] + } + } +} +``` + +## 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.DSC/PowerShell resource][02] +- For more information about OpenSSH, see [OpenSSH Documentation][03] + + +[00]: ../../../../../concepts/resources/capabilities.md +[01]: ./examples/configure-default-shell-powershell.md +[02]: ../../../DSC/PowerShell/index.md +[03]: /windowsserverdocs/WindowsServerDocs/administration/OpenSSH/openssh-overview 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