{"id":14063761,"url":"https://github.com/loanDepot/WslHelper","last_synced_at":"2025-07-29T16:31:46.267Z","repository":{"id":171826662,"uuid":"647340539","full_name":"loanDepot/WslHelper","owner":"loanDepot","description":"Functions to help install, upgrade and configure WSL for developers (particularly behind corporate firewalls).","archived":false,"fork":false,"pushed_at":"2023-07-13T20:20:07.000Z","size":21,"stargazers_count":7,"open_issues_count":0,"forks_count":2,"subscribers_count":1,"default_branch":"main","last_synced_at":"2024-08-13T07:05:29.866Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"PowerShell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/loanDepot.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null}},"created_at":"2023-05-30T15:09:01.000Z","updated_at":"2024-07-02T10:40:44.000Z","dependencies_parsed_at":"2024-02-07T16:57:46.228Z","dependency_job_id":"f17922ec-65aa-42de-945d-9cc8569df544","html_url":"https://github.com/loanDepot/WslHelper","commit_stats":null,"previous_names":["loandepot/wslhelper"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/loanDepot%2FWslHelper","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/loanDepot%2FWslHelper/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/loanDepot%2FWslHelper/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/loanDepot%2FWslHelper/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/loanDepot","download_url":"https://codeload.github.com/loanDepot/WslHelper/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":228028620,"owners_count":17858419,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-13T07:03:29.822Z","updated_at":"2024-12-04T01:31:27.351Z","avatar_url":"https://github.com/loanDepot.png","language":"PowerShell","funding_links":[],"categories":["PowerShell"],"sub_categories":[],"readme":"# WSL Helper Functions\n\nThese automate configuration we find ourselves repeating on everyone's Windows laptops at work.\n\nMost of the functions were pulled from Joel \"Jaykul\" Bennett's personal [box-starter](https://github.com/Jaykul/BoxStarter-Boxes/blob/main/10_DevOps/WSL.psm1) or [gists](https://gist.github.com/Jaykul/315f7413752a92997390bf2ef052bc17) or [dotfiles](https://github.com/Jaykul/dotfiles) and put here so we would have one single place to look for them.\n\n## Assumptions\n\n\u003e There was no Jedi so wise that he could not be undone by his own assumptions.\n― Claudia Gray, Master and Apprentice\n\n1. You **must** be on WSL v2.\n2. Your WSL Linux username should be your Windows username, all lower case. If not, you should pass it to any function with a `-UserName` parameter.\n3. You install WSL distros through `Install-WslDistro`\n4. You mostly use Ubuntu (and thus, use `apt` for package management)\n5. WSL \"distros\" with names that start with \"docker-\" or end with \"-data\" are ignored\n\nMany of these functions will not work when these assumptions are false. Most of these functions do not have alternate logic for dealing with additional Linux distros or package managers yet.\n\nNOTE: Some default values include things which are specific to LoanDepot. These have been done carefully, such that if these functions are run on a personal laptop, the LoanDepot values are irrelevant.\n\n## Getting Started\n\nIf you've not used this module before, please make sure to read the [Assumptions](#assumptions) above.\n\n### First things first\n\nWe need to make sure you're using the current version of WSL, so you need to run `wsl --update` before anything else. If you check your `wsl --version` you should see the WSL version is 1.2 or higher, and you should see the linux Kernel version 5.15 or higher, and WSLg should be available.\n\nIf you have existing wsl distributions installed, check to make sure they are running on WSL 2 by using the `wsl --list --verbose` command. If they are not, remove them with `wsl --unregister $distroname` and install new copies.\n\n```bash\nwsl --update\nwsl --version\nwsl --list --verbose\n```\n\n## Installing WSL Tools\n\ntl;dr:\n\nImport the module and run these commands in PowerShell on Windows:\n\n```powershell\nInstall-WslDistro -Default\nUpdate-WslCertificates -Verbose\nwsl ping google.com -c3 || Update-WslDns -Verbose\nUpdate-WslUbuntu\nInstall-WslPowerShellSnap\nInstall-WslKubectlSnap\n```\n\n### Update WSL\n\nSee [first things first](#first-things-first) above.\n\n### Install ubuntu\n\n```powershell\nInstall-WslDistro\n```\n\nIf you're running this by hand, you'll be prompted for a password, which you'll need to remember whenever you need to `sudo` to run something as root...\n\n### Copy private CA certificates\n\nIf you are using a private (internal) CA that's basically self-signed, or if you're using ZScaler (with it's self-signed certificate) then you need to add those CA certificates to WSL's trust list. You can pass a list of their thumbprints to `Update-WslCertificates`.\n\nIf you look at the default value, I wrote this so it works for LoanDepot with _no parameters_, but you just need to run something like:\n\n```powershell\nGet-ChildItem Cert:\\LocalMachine\\Root | Where-Object Subject -Match \"ZScaler\" | Update-WslCertificates\n```\n\n### Make sure your network is working\n\nWe've had frequent problems with networking. Particularly, older versions of AnyConnect break WSL networking and requires the VPN to be reconfigured to work correctly. ZScaler Private Access works properly for us, but still somehow breaks Window's ability to configured DNS for WSL.\n\nTest with: `wsl ping google.com` -- if that does not work, try with `wsl ping 8.8.8.8`.\n\nIf you can't connect at all, you'll need to disconnect your VPN, and possibly restart WSL -- you can quickly `wsl --terminate ubuntu` and then check with `wsl --list --running` to ensure it's stopped before you re-run the ping commands.\n\nIf you can ping the ip address but not the domain name, then you just need to fix your WSL Dns.\n\n```powershell\nUpdate-WslDns\n```\n\n**Important:** this disables and replaces the automated configuration. You will probably need to re-run this command whenever you change the network that you're connected to.\n\n### Update Linux\n\nSince WSL distros are not included in Windows Update, you periodically need to update the software in them -- including _right after install_. Run:\n\n```powershell\nUpdate-WslUbuntu\n```\n\nNote that this installs and uses `aptitude` because it's a better experience than using apt-get or apt.\nThe other `Install` functions depend on this (unless they say \"Snap\"), and will call it to ensure aptitude is installed.\n\n### Installing additional tools.\n\nThere are a lot of ways to install our tools like powershell, kubectl, and helm.\nNow that WSL 2 supports systemd, Ubuntu in WSL supports snap, which makes that _by far_ the simplest way to install things.\nWe still have wrapper scripts for a few pieces of this, but you can probably just `sudo snap install ...`\n\n\n#### Install PowerShell on Linux:\n\nIf you need to use PowerShell scripts in linux, or are more comfortable with pwsh than with bash, you will want to install it:\n\n```powershell\nInstall-WslUbuntuPwsh\n```\n\n#### Install SSH Agent forwarding:\n\nIf you frequently connect via `ssh` and have configured the Windows OpenSSH Agent service, or KeePass and KeeAgent, or some other agent, you'll want to configure SSH Agent forwarding using socat:\n\n```powershell\nInstall-WslSshAgentPipe\n```\n\n#### Install Kubernetes tools\n\nThis function installs kubelogin (for azure), kubectl, and helm, and needs to be updated each release to install the specific (old) version of kubectl we need for working with our \"stable\" AKS clusters in Azure.\n\n```powershell\nInstall-WslK8sTools\n```\n\n## CAUTION:\n\nEvery time Microsoft makes significant changes to WSL, some of these functions become unnecessary, and others break.\n\nToday is May 20, 2023, and our oldest desktops are running Windows 10.0.19042.\n\nThe current version of PowerShell is 7.3.4\n\nThe current version of Ubuntu in WSL is 20.04\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FloanDepot%2FWslHelper","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FloanDepot%2FWslHelper","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FloanDepot%2FWslHelper/lists"}