genie

A quick way into a systemd "bottle" for WSL

What does that even mean?

Well, this gives you a way to run systemd as pid 1, with all the trimmings, inside WSL 2. It does this by creating a pid namespace, the eponymous poor-man's-container "bottle", starting up systemd in there, and entering it, and providing some helpful shortcuts to do so.

WSL NOW HAS NATIVE SYSTEMD SUPPORT

As explained here, if you are running Windows 11 and a version of WSL 0.67.6 or above. If this is available to you, you should use it instead of genie, because it's a much more elegant way of getting systemd to run.

It's not quite perfect, however, so you should also check out bottle-imp, my friendly helper to make working with WSL's native systemd support a little easier.

Using genie on systems that have native systemd support is not supported.

REQUIREMENTS

NOTE: Before you install genie for the first time, read ALL of this page. This will save you a great deal of trouble later on. Especially, please note that on many distributions you will encounter the problem described under "Warning: Timing Out" below when you first run genie, and will need to resolve it before your system will operate correctly.

It is a good idea to set your systemd default target to multi-user.target before installing genie. This is the target that genie is designed to work with, since the default graphical.target used by many distributions includes services for the graphical desktop that would take, at minimum, considerable reconfiguration before operating properly under the WSL/WSLg environment.

If you are using a custom kernel for WSL, it should comply with the suggested means of detecting WSL given in https://github.com/Microsoft/WSL/issues/423#issuecomment-221627364 - i.e., the string "microsoft" should be present in the kernel version string, which can be found in /proc/sys/kernel/osrelease. You can check this by running systemd-detect-virt; it should return "wsl".

Also read the WSLg FAQ and the known-problematic systemd units list for known problems and known solutions to them.

More information, tips & tricks, etc. are available on the genie wiki. Please consult it before opening an issue.

NOTE: WSL 2 ONLY

Note: it is only possible to run systemd (and thus genie ) under WSL 2; WSL 1 does not support the system calls required to do so. If you are running inside a distro configured as WSL 1, even if your system supports WSL 2, genie will fail to operate properly.

INSTALLATION

If there is a package available for your distribution, this is the recommended method of installing genie.

Debian

Dependent packages on Debian are daemonize, dbus, gawk, libc6 (>= 2.2.5), policykit-1, python3 (>= 3.7), python3-pip, python3-psutil, systemd (>= 232-25), and systemd-container (>= 232-25). These should all be in the distro and able to be installed automatically.

To install, add the wsl-translinux repository here by following the instructions here:

https://arkane-systems.github.io/wsl-transdebian/

then install genie using the commands:

sudo apt update
sudo apt install -y systemd-genie

Ubuntu & Other Debian Derivatives

Use the above Debian package. For current Ubuntu releases and the timing-out problem, see the problematic units listed on the genie wiki.

Arch

An Arch package (.zst) can be downloaded from the releases, to right. Install it manually, using pacman -U <file>.

Fedora

A Fedora package (.rpm) can be downloaded from the releases, to right. Install it manually, using dnf install <file>.

Other Distros

If your distribution supports any of the package formats available, you may wish to try downloading the relevant format and giving it a try. This will almost certainly need some tweaking to work properly.

Debian is the "native" distribution for genie , for which read, "what the author uses". Specifically, Debian buster+, with usrmerge installed. If you're using anything else, you may need to tweak the configuration file (see below) accordingly.

TAR

There is a .tar.gz of a complete genie install available from the releases, to right. As a last resort, you can try untarring this (it contains every needed file, with the correct permissions, in the correct path from /) onto your system while root. Don't do this unless you're confident you know what you're doing, you're willing to go looking for any resulting issues yourself, and you aren't afraid of accidentally breaking things. You will need to install the dependencies listed above beforehand.

Maintainers Wanted!

We're actively looking for maintainers for everything that doesn't have a specific package. If you have the time, please contribute.

I am unable to support distributions which there are not prebuilt packages for. I am actively seeking maintainers for these packages.

CONFIGURATION FILE

That would be the file /etc/genie.ini. This defines the secure path (i.e., those directories in which genie will look for the utilities it depends on; make sure unshare, in particular, is available here), and seven settings controlling genie behavior. Normally, it looks like this:

[genie]
secure-path=/lib/systemd:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
update-hostname=true
update-hostname-suffix=-wsl
clone-path=false
clone-env=WSL_DISTRO_NAME,WSL_INTEROP,WSLENV,DISPLAY,WAYLAND_DISPLAY,PULSE_SERVER
systemd-timeout=240
resolved-stub=false
target-warning=true

The secure-path setting should be generic enough to cover all but the weirdest Linux filesystem layouts, but on the off-chance that yours stores binaries somewhere particularly idiosyncratic, you can change it here.

The update-hostname setting controls whether or not genie updates the WSL hostname when creating the bottle. By default, genie updates a hostname foo to foo-wsl, to prevent hostname clashes between the host Windows machine and the WSL distribution, especially when communicating back and forth between the two.

However, as recent WSL builds allow the hostname of the WSL distributions to be set in .wslconfig, this option has been provided to disable genie's intervention and keep the original hostname. Additionally, the update-hostname-suffix setting allows you to change the suffix added to the original hostname to create the WSL hostname.

HOWEVER if you are using bridged networking, which uses separate IP addresses for WSL, often acquired via DHCP, we strongly recommend not disabling this feature. On many networks, acquiring an address for WSL via DHCP with the same hostname as your Windows machine will remove your Windows machine's IP address from DNS, with irritatingly vague consequences.

The clone-path setting controls whether the PATH outside the bottle should be cloned inside the bottle. This can be useful since the outside-bottle path may include system-specific directories not mentioned in secure-path, and since the outside-bottle path includes a transformed version of the host machine's Windows path.

If this is set to true, the inside-bottle path will be set to the secure-path combined with the outside-bottle path, with duplicate entries removed. It is set to false by default, for backwards compatibility.

The clone-env setting lists the environment variables which are copied from outside the bottle to inside the bottle. It defaults to only WSL_DISTRO_NAME, WSL_INTEROP, and WSLENV, needed for correct WSL operation, plus DISPLAY, WAYLAND_DISPLAY, and PULSE_SERVER, needed for WSLg but any other environment variables which should be cloned can be added to this list.

The systemd-timeout setting controls how long (the number of seconds) genie will wait when initializing the bottle for systemd to reach its "running" - i.e. fully operational, with all units required by the default target active - state. This defaults to 240 seconds.

genie (1.44+) provides the resolved-stub option to automatically back up the existing /etc/resolv.conf and replace it with the symlink necessary to run systemd-resolved in stub mode when initializing the bottle, and revert to the backup when the bottle terminates. (NOTE: This last is a courtesy and should NOT be interpreted as meaning idempotency is supported in any way; see BUGS .) 1.43 performed this action by default; upgraders from 1.43 who wish to retain this behavior must set resolved-stub=true in the configuration file.

By default, genie (2.0+) warns you upon bottle initialization if the default systemd target is not multi-user.target, since this is the default with which genie is designed to work. If you have configured a different systemd target to run correctly with genie, this warning can be disabled by setting target-warning to false in the config file.

genie (1.39+) also installs a pair of systemd units (wslg-xwayland.service and wslg-xwayland.socket and an override for user-runtime-dir@.service) to ensure that WSLg operates correctly from inside the bottle. If desired, these can be disabled and enabled independently of genie itself.

USAGE

usage: genie [-h] [-V] [-v] [-a USER] (-i | -s | -l | -c ... | -u | -r | -b)

Handles transitions to the "bottle" namespace for systemd und

Genie

Install / Use

README