Proposal: SSHDConfig Set Support for Repeatable Keywords

[tgauth]

Summary of the new feature / enhancement

The Microsoft.OpenSSH/SSHDConfig resource currently supports setting sshd_config keywords only when _purge: true, which replaces the entire configuration file. When _purge: false, there is ambiguity in handling keywords that can have multiple arguments. Keywords that can have multiple arguments are further divided into three categories: repeatable, comma-separated, and space-separated. Repeatable keywords (like Subsystem and Port) are spread over multiple lines. Comma-separated (like Ciphers) and space-separated (like AuthorizedKeysFile) keywords can have multiple arguments on a single line. Note, the keywords that are both space-separated and repeatable (i.e. AllowUsers) are classified under "repeatable" for the scope of this discussion.

Proposed technical implementation details (optional)

This proposal builds on the ideas previously discussed in #790 and #1070 to suggest handling these keywords through the following:

1. For all keywords: the Microsoft.OpenSSH/SSHDConfig resource simply passes the declared value through directly (overwriting any existing value(s) that may exist for that keyword)
2. For repeatable keywords: the Microsoft.OpenSSH/SSHDConfig.Repeatable resource with _exist facilitates addition/removal of specific entries

Examples:

Set - behaves as overwrite for all keyword types

- type: Microsoft.OpenSSH/SSHDConfig
  properties:
    PasswordAuthentication: false
    Ciphers:
     - +aes256-gcm@openssh.com
    Port:
     - 2222

Set - behaves as "add" for repeatable keywords

- type: Microsoft.OpenSSH/SSHDConfig.Repeatable
  properties:
    _exist: true
    subsystem:
      - "powershell /usr/bin/pwsh -sshs -NoLogo"
    port:
      - 3333

Set - behaves as "remove" for repeatable keywords

- type: Microsoft.OpenSSH/SSHDConfig.Repeatable
  properties:
    _exist: false
    subsystem:
      - "powershell /usr/bin/pwsh -sshs -NoLogo"
    port:
      - 3333

[SteveL-MSFT]

I think for Microsoft.OpenSSH/SSHDConfig, it should always just overwrite. If they want to add/remove, they MUST use the Repeatable type

[tgauth]

Summary of the WG discussion:

1.Microsoft.OpenSSH/SSHDConfig will always overwrite.
2. Individual resources will be created for configuring repeatable/multi-arg keywords.

Example: Subsystem resource with _exist

resources:.SSHD/Subsystem
  name: AddSFTPSubsystem
  properties:
    _exist: true
    name: sftp
    value: /usr/lib/ssh/sftp-server

- type: Microsoft.OpenSSH.SSHD/Subsystem
  name: RemoveSFTPSubsystem
  properties:
    _exist: false
    name: sftp

Example: SubsystemList resource with _purge

resources:
- type: Microsoft.OpenSSH.SSHD/SubsystemList
  name: SetSubsystems
  properties:
    subsystems:
      - name: sftp
        value: /usr/lib/ssh/sftp-server
      - name: custom
        value: /opt/custom-subsystem
    _purge: true

The full list of applicable keywords can be found in: https://github.com/PowerShell/DSC/blob/main/resources/sshdconfig/src/metadata.rs

[theJasonHelmick]

The DSC WG discussed how to handle repeatable keywords in sshd_config (for example Port) and agreed to keep the model simple and predictable.

The top-level sshd_config resource is meant to be overwrite-only and used when you want to manage the whole file. For repeatable keywords, we should instead use smaller, focused resources (for example PortList) so it’s clear that multiple values are being managed.

For these list-style resources, the main behavior is purge vs. not purge:
• With purge enabled, the list you provide is the source of truth and anything else is removed.
• With purge disabled, values are added without removing existing ones.

We explicitly decided not to support prepend, merge, or positional logic for now, since that adds a lot of complexity and makes ownership harder to reason about. If order matters, the expectation is that you define the full list and enable purge.

This keeps the behavior easy to understand, avoids surprises, and matches how we already handle similar cases elsewhere in DSC.