Skip to content

sc-021.md

Latest commit

 

History

History
68 lines (51 loc) · 3.03 KB

sc-021.md

File metadata and controls

68 lines (51 loc) · 3.03 KB

← Back to Backlog

[SC-021] ✅ DONE — Apply default WSL global settings (.wslconfig) via wsl-manager

Status

Status: Done (2026-03-11)

Description

Add a configure-wsl command to wsl-manager that idempotently applies a recommended set of default global WSL settings to %USERPROFILE%\.wslconfig.

The targeted defaults are:

[wsl2]
kernelCommandLine = cgroup_no_v1=all systemd.unified_cgroup_hierarchy=1
networkingMode = mirrored
dnsTunneling = true
autoProxy = true

No existing user values are overwritten. A timestamped backup is created before any modification.

Use Cases

  • Developer sets up a new Windows machine and wants sensible WSL2 defaults applied in one step.
  • cgroup v2 is required for systemd inside WSL (enables rootless Docker/Podman without workarounds).
  • Mirrored networking + DNS tunneling + auto-proxy improve corporate proxy compatibility.
  • Idempotent design means the command is safe to re-run after manual edits.

Behaviour Rules

Scenario Expected behaviour
.wslconfig does not exist Create the file with all defaults
.wslconfig exists but has no [wsl2] section Append the [wsl2] section with defaults
[wsl2] section exists, key is missing Add the missing key with its default value
[wsl2] section exists, key is already set Leave the existing value untouched
kernelCommandLine exists with extra user params Append only the missing default params
Run the command a second time (idempotent) No changes, no backup

Acceptance Criteria

  • wsl-manager configure-wsl applies all four defaults when .wslconfig is absent.
  • wsl-manager configure-wsl appends [wsl2] when the section is missing from an existing file.
  • Each missing key is added individually; present keys are not touched.
  • User's custom value for any key is preserved.
  • kernelCommandLine: missing default parameters are appended to the existing value.
  • kernelCommandLine: no change when all default parameters are already present.
  • A timestamped .wslconfig.bak.<timestamp> backup is created before any write.
  • No backup is created when no changes are needed.
  • Running the command twice produces identical output (idempotent).
  • [W] Configure .wslconfig defaults is available in the interactive menu.
  • -WhatIf shows what would change without writing the file.
  • Post-apply output hints to run wsl-manager shutdown to apply changes.

Technical Notes

  • Implementation: Invoke-ConfigureWsl in ops.ps1, Invoke-ConfigureWslDefault in commands.ps1.
  • INI parsing is line-based (no external library) to keep PS 5.1 compatibility.
  • Merge-WslConfig is a pure helper function: given lines + defaults, returns updated lines + changed flag.
  • Menu key: W (.wslconfig). Note: C is already taken by "clone".
  • .wslconfig path: $env:USERPROFILE\.wslconfig (Windows-side file, not inside WSL).
  • The command does not auto-shutdown WSL; it only hints the user to do so.

← Back to Backlog