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..be276e794 --- /dev/null +++ b/docs/reference/resources/Microsoft/OpenSSH/SSHD/Windows/examples/configure-default-shell-powershell.md @@ -0,0 +1,108 @@ +--- +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, set `shell` to an empty string. The resource +removes the `DefaultShell` registry value when the property is set to `""`: + +```powershell +$cleanup = @{ shell = '' } | ConvertTo-Json +dsc resource set --resource Microsoft.OpenSSH.SSHD/Windows --input $cleanup +``` + +Alternatively, you can remove the registry value directly: + +```powershell +$params = @{ + Path = 'HKLM:\SOFTWARE\OpenSSH' + Name = 'DefaultShell' + ErrorAction = 'SilentlyContinue' +} +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..75581e160 --- /dev/null +++ b/docs/reference/resources/Microsoft/OpenSSH/SSHD/Windows/index.md @@ -0,0 +1,199 @@ +--- +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 server global configuration settings on Windows. + +## 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: + cmdOption: + escapeArguments: +``` + +## Condition + +The resource only applies on systems where the `sshd` executable is available in PATH. DSC +evaluates this with the expression `[not(equals(tryWhich('sshd'), null()))]` and skips the +resource if `sshd` is not found. + +## Description + +The `Microsoft.OpenSSH.SSHD/Windows` resource enables you to idempotently manage the Windows +OpenSSH server global settings. These settings are stored in the Windows registry under +`HKLM\SOFTWARE\OpenSSH` and control the default shell behavior for SSH sessions: + +- Set the default shell executable for SSH connections. +- Specify command-line options to pass to the default shell. +- Control whether shell arguments are escaped. + +> [!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 or later. + +## 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. +When specified, the value must be 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 will be +properly escaped before being passed to the shell. + +## Instance validating schema + +The resource generates its schema dynamically at runtime by running +`sshdconfig schema -s windows-global`. The following snippet shows the effective schema that +validates an instance of the resource. + +```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..521879b84 --- /dev/null +++ b/docs/reference/resources/Microsoft/OpenSSH/SSHD/sshd_config/examples/export-openssh-configuration.md @@ -0,0 +1,81 @@ +--- +description: > + Example showing how to use Microsoft.OpenSSH.SSHD/sshd_config to export current SSH server + configuration settings. +ms.date: 05/07/2026 +ms.topic: reference +title: Export OpenSSH SSH server configuration +--- + +# Export OpenSSH SSH server configuration + +This example demonstrates how to use the `Microsoft.OpenSSH.SSHD/sshd_config` resource with the +[dsc resource export][00] command to retrieve all current SSH server configuration settings as a +DSC configuration document that you can save and re-apply later. + +> [!NOTE] +> You should run this example in an elevated context (as Administrator on Windows, or with `sudo` +> on Linux) to ensure the SSH server configuration can be read successfully. + +## Export the current SSH server configuration + +Run the following command to export the current `sshd_config` settings: + +```powershell +dsc resource export --resource Microsoft.OpenSSH.SSHD/sshd_config +``` + +DSC returns a configuration document with one resource instance per exported setting. The output +looks similar to the following, where the exact properties and values reflect what is currently +configured on the system: + +```yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +resources: +- name: Microsoft.OpenSSH.SSHD/sshd_config[0] + type: Microsoft.OpenSSH.SSHD/sshd_config + properties: + port: '22' + addressfamily: any + listenaddress: '0.0.0.0' + syslogfacility: AUTH + loglevel: INFO + logingracetime: 120 + strictmodes: 'yes' + maxauthtries: 6 + pubkeyauthentication: 'yes' + authorizedkeysfile: .ssh/authorized_keys + passwordauthentication: 'no' + permitemptypasswords: 'no' + challengeresponseauthentication: 'no' + kerberosauthentication: 'no' + gssapiauthentication: 'no' + usepam: 'yes' + x11forwarding: 'no' + printmotd: 'no' + acceptenv: LANG LC_* + subsystem: sftp /usr/lib/openssh/sftp-server +``` + +> [!NOTE] +> The output is truncated in this example. The actual output includes all effective +> `sshd_config` directives for your system, including defaults inherited from OpenSSH. + +## Save the export to a configuration file + +You can pipe the export output to a file to create a backup of your current SSH server +configuration: + +```powershell +dsc resource export --resource Microsoft.OpenSSH.SSHD/sshd_config > sshd_backup.dsc.config.yaml +``` + +To re-apply the saved configuration to a system, use the [dsc config set][01] command: + +```powershell +dsc config set --document sshd_backup.dsc.config.yaml +``` + + +[00]: ../../../../../../cli/resource/export.md +[01]: ../../../../../../cli/config/set.md diff --git a/docs/reference/resources/Microsoft/OpenSSH/SSHD/sshd_config/examples/manage-sshd-settings.md b/docs/reference/resources/Microsoft/OpenSSH/SSHD/sshd_config/examples/manage-sshd-settings.md new file mode 100644 index 000000000..10cd4e41c --- /dev/null +++ b/docs/reference/resources/Microsoft/OpenSSH/SSHD/sshd_config/examples/manage-sshd-settings.md @@ -0,0 +1,113 @@ +--- +description: > + Example showing how to use Microsoft.OpenSSH.SSHD/sshd_config to get and enforce specific SSH + server configuration settings. +ms.date: 05/07/2026 +ms.topic: reference +title: Manage SSH server configuration settings +--- + +# Manage SSH server configuration settings + +This example demonstrates how to use the `Microsoft.OpenSSH.SSHD/sshd_config` resource to check +and enforce secure SSH server configuration settings, such as disabling password-based +authentication. + +> [!NOTE] +> You should run this example in an elevated context (as Administrator on Windows, or with `sudo` +> on Linux) to ensure the SSH server configuration can be updated successfully. + +## Get the current state of specific settings + +The following snippet shows how to use the [dsc resource get][00] command to retrieve the current +values of specific `sshd_config` directives. + +```powershell +$instance = @{ + passwordauthentication = 'no' + permitrootlogin = 'no' +} | ConvertTo-Json + +dsc resource get --resource Microsoft.OpenSSH.SSHD/sshd_config --input $instance +``` + +When the settings differ from the desired values, DSC returns the current state from the +`sshd_config` file: + +```yaml +actualState: + passwordauthentication: 'yes' + permitrootlogin: prohibit-password +``` + +## Test whether the settings are in the desired state + +Use the [dsc resource test][01] command to check whether the current settings match your desired +values: + +```powershell +dsc resource test --resource Microsoft.OpenSSH.SSHD/sshd_config --input $instance +``` + +When the settings are not in the desired state, DSC returns the following result: + +```yaml +desiredState: + passwordauthentication: 'no' + permitrootlogin: 'no' +actualState: + passwordauthentication: 'yes' + permitrootlogin: prohibit-password +inDesiredState: false +differingProperties: +- passwordauthentication +- permitrootlogin +``` + +## Enforce the desired settings + +Use the [dsc resource set][02] command to apply the desired settings: + +```powershell +dsc resource set --resource Microsoft.OpenSSH.SSHD/sshd_config --input $instance +``` + +DSC updates the `sshd_config` file and returns the before and after states: + +```yaml +beforeState: + passwordauthentication: 'yes' + permitrootlogin: prohibit-password +afterState: + passwordauthentication: 'no' + permitrootlogin: 'no' +changedProperties: +- passwordauthentication +- permitrootlogin +``` + +Test the instance again to confirm that the settings are now in the desired state: + +```powershell +dsc resource test --resource Microsoft.OpenSSH.SSHD/sshd_config --input $instance +``` + +```yaml +desiredState: + passwordauthentication: 'no' + permitrootlogin: 'no' +actualState: + passwordauthentication: 'no' + permitrootlogin: 'no' +inDesiredState: true +differingProperties: [] +``` + +> [!IMPORTANT] +> After changing `sshd_config` settings, restart the SSH server service for the changes to take +> effect. On Windows, run `Restart-Service sshd`. On Linux, run `sudo systemctl restart sshd`. + + +[00]: ../../../../../../cli/resource/get.md +[01]: ../../../../../../cli/resource/test.md +[02]: ../../../../../../cli/resource/set.md 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..6a6ce0df9 --- /dev/null +++ b/docs/reference/resources/Microsoft/OpenSSH/SSHD/sshd_config/index.md @@ -0,0 +1,139 @@ +--- +description: Microsoft.OpenSSH.SSHD/sshd_config resource reference documentation +ms.date: 05/07/2026 +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 +Author : Microsoft +``` + +## Instance definition syntax + +```yaml +resources: + - name: + type: Microsoft.OpenSSH.SSHD/sshd_config + properties: + # Any sshd_config directive as a key + : +``` + +## Condition + +The resource only applies on systems where the `sshd` executable is available in PATH. DSC +evaluates this with the expression `[not(equals(tryWhich('sshd'), null()))]` and skips the +resource if `sshd` is not found. + +## Description + +The `Microsoft.OpenSSH.SSHD/sshd_config` resource enables you to idempotently manage SSH server +configuration settings stored in the `sshd_config` file. The resource can: + +- Retrieve current SSH server configuration settings. +- Apply desired SSH server configuration settings. +- Export all current SSH server configuration settings as individual resource instances. + +> [!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 to be installed on the system. +- The resource must run in a process context that has permissions to read and write the `sshd_config` + file. +- On Windows, the default configuration file path is `%ProgramData%\ssh\sshd_config`. +- On Linux, the default configuration file path is `/etc/ssh/sshd_config`. + +## 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 all current SSH server configuration settings as + individual resource 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. [Export OpenSSH configuration][01] - Shows how to export current OpenSSH configuration. +2. [Manage SSH server configuration settings][02] - Shows how to get and set specific sshd_config + directives. + +## Properties + +The `Microsoft.OpenSSH.SSHD/sshd_config` resource uses an open-object schema where each property +corresponds to an `sshd_config` directive. There are no fixed required or key properties. Any +valid `sshd_config` keyword can be used as a property name with its corresponding value. + +For example: + +```yaml +PermitRootLogin: 'no' +PasswordAuthentication: 'no' +Port: 22 +``` + +For the full list of supported directives and their values, see the +[sshd_config man page][05] or the OpenSSH documentation. + +## Instance validating schema + +The resource uses an embedded open-object schema. Any `sshd_config` directive is a valid property. + +```json +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "title": "sshdconfig", + "type": "object", + "properties": {}, + "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]: ../../../../../concepts/resources/capabilities.md +[01]: examples/export-openssh-configuration.md +[02]: examples/manage-sshd-settings.md +[03]: ../Windows/index.md +[04]: /windowsserverdocs/WindowsServerDocs/administration/OpenSSH/openssh-overview +[05]: https://man.openbsd.org/sshd_config