Skip to content

Commit e3db3a6

Browse files
authored
[DOCS] Persisting vm.max_map_count for WSL2 (#87276)
1 parent 2ce7581 commit e3db3a6

File tree

1 file changed

+40
-2
lines changed

1 file changed

+40
-2
lines changed

docs/reference/setup/install/docker.asciidoc

Lines changed: 40 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -399,14 +399,52 @@ sudo sysctl -w vm.max_map_count=262144
399399

400400
====== Windows with https://docs.docker.com/docker-for-windows/wsl[Docker Desktop WSL 2 backend]
401401

402-
The `vm.max_map_count` setting must be set in the docker-desktop container:
402+
The `vm.max_map_count` setting must be set in the "docker-desktop" WSL instance before the
403+
ElasticSearch container will properly start. There are several ways to do this, depending
404+
on your version of Windows and your version of WSL.
405+
406+
If you are on Windows 10 before version 22H2, or if you are on Windows 10 version 22H2 using the
407+
built-in version of WSL, you must either manually set it every time you restart Docker before starting
408+
your ElasticSearch container, or (if you do not wish to do so on every restart) you must globally set
409+
every WSL2 instance to have the `vm.max_map_count` changed. This is because these versions of WSL
410+
do not properly process the /etc/sysctl.conf file.
411+
412+
To manually set it every time you reboot, you must run the following commands in a command prompt
413+
or PowerShell window every time you restart Docker:
403414

404415
[source,sh]
405416
--------------------------------------------
406-
wsl -d docker-desktop
417+
wsl -d docker-desktop -u root
407418
sysctl -w vm.max_map_count=262144
408419
--------------------------------------------
409420

421+
If you are on these versions of WSL and you do not want to have to run those commands every
422+
time you restart Docker, you can globally change every WSL distribution with this setting
423+
by modifying your %USERPROFILE%\.wslconfig as follows:
424+
425+
[source,text]
426+
--------------------------------------------
427+
[wsl2]
428+
kernelCommandLine = "sysctl.vm.max_map_count=262144"
429+
--------------------------------------------
430+
431+
This will cause all WSL2 VMs to have that setting assigned when they start.
432+
433+
If you are on Windows 11, or Windows 10 version 22H2 and have installed the Microsoft Store
434+
version of WSL, you can modify the /etc/sysctl.conf within the "docker-desktop" WSL
435+
distribution, perhaps with commands like this:
436+
437+
[source,sh]
438+
--------------------------------------------
439+
wsl -d docker-desktop -u root
440+
vi /etc/sysctl.conf
441+
--------------------------------------------
442+
443+
and appending a line which reads:
444+
[source,text]
445+
--------------------------------------------
446+
vm.max_map_count = 262144
447+
--------------------------------------------
410448

411449
===== Configuration files must be readable by the `elasticsearch` user
412450

0 commit comments

Comments
 (0)