Skip to main content

Automatically Configuring WSL

Avatar

Craig

Beginning with Insider Build 17093, we added a method for you to automatically configure certain functionality in WSL that will be applied every time you launch the subsystem. This includes automount options and network configuration.

We’re introducing a file called wsl.conf to handle these configurations. For example, we released a blog post in the past about file system improvements in DrvFs. In order for a user to take advantage of this feature, they had to unmount and re-mount DrvFs each time they launched WSL–this is not the case any longer.

How to use wsl.conf

Wsl.conf belongs under the path /etc/wsl.conf. If the file is not there, you can create it yourself. WSL will detect the existence of the file and will read its contents. If the file is missing or malformed (that is, improper markup formatting), WSL will continue to launch as normal.

The format of wsl.conf is modeled after .ini files–like .gitconfig files. Below is a sample that you could drop into your distros:

In the example below, I’ll tell WSL that I would like my drives to mount automatically with metadata enabled. Notice how I must exit and reload WSL after making the change to wsl.conf so that WSL reads in my changes on launch.

Configuration Options

In keeping with .ini conventions, keys are declared under a section. In WSL today, we have two sections: “automount” and “network”. Below are key-values that can be set:

Section: automount

Key: enabled Value: Boolean value [true, false]
Default: true
Setting to true causes your fixed drives (i.e C:/ or D:/) to be automatically mounted with DrvFs under “/mnt”. Setting to false means they won’t be mounted automatically—but you could still mount them manually or via fstab.
Key: mountFsTab Value: Boolean value [true, false]
Default: true
Setting to true causes the file /etc/fstab to be processed on WSL start. /etc/fstab is a file where you can declare other filesystems, like an SMB share. Thus, you can mount these filesystems automatically in WSL on start up.
Key: root Value: String value (/mnt/…)
Default: “/mnt/”
This key lets you define a new directory where fixed drives will be automatically mounted. For example, if you have a directory in WSL at “/windir/” and you specify that as the root, you would expect to see your fixed drives (for example, C:/) mounted at “/windir/c”
Key: options Value: comma-separated list of values
Default: No options specified
This value is appended to the default DrvFs mount options string. Only DrvFs-specific options can be specified. These can be found in an earlier blog post. Options that the mount binary would normally parse into a flag are not supported. If you want to explicitly specify those options, you must include every drive for which you want to do so in /etc/fstab. By default, WSL sets the uid and gid to the value of the default user (in Ubuntu distro, the default user is created with uid=1000,gid=1000). If the user specifies a gid or uid option explicitly via this key, the associated value will be overwritten. Otherwise, the default value will always be appended. Note: These options are applied as the mount options for all automatically mounted drives. To change the options for a specific drive only, use /etc/fstab instead.

Section: network

Key: generateHosts Value: Boolean value [true, false]
Default: true
Setting this key will determine whether WSL will generate /etc/hosts. The “hosts” file contains a static list or map of hostnames to their corresponding IP address.
Key: generateResolvConf Value: Boolean value [true, false]
Default: true
Setting this key will determine whether WSL will generate /etc/resolv.conf. The “resolv.conf” file contains a DNS list that are capable of resolving a given hostname to its IP address.

 

Section: interop

These options are available in Insider Build 17713 and later.

Key: enabled Value: Boolean value [true, false]
Default: true
Setting this key will determine whether WSL will support launching Windows processes.
Key: appendWindowsPath Value: Boolean value [true, false]
Default: true
Setting this key will determine whether WSL will add Windows path elements to the $PATH environment variable.

 

What Else?

You can consult the Microsoft Docs as a reference. Are there other configurations you’d like to make to WSL? What other options would you like to be able to specify in wsl.conf? Leave us a comment below. Cheers!

Craig Wilhite (@CraigWilhite) Ben Hillis (@BenHillis)

Avatar
Craig Wilhite

Program Manager,  WSL, Containers, and Hyper-V

Follow Craig   

No Comments.