qnighy / genie-rs

A quick way into a systemd "bottle" for WSL -- Rust port

This is a work-in-progress Rust port of genie. The description below may be incorrect for the Rust port.

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.

If you want to try it, please read this entire document first, especially the BUGS section.

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, dotnet-runtime-3.1, policykit-1, and systemd . For the most part, these are either already installed or in the distro and able to be installed automatically. You need debhelper and dotnet-sdk-3.1 (and optionally pbuilder) to build the Debian package, but not to simply build genie or install locally.

The chief exception is dotnet-runtime-3.1 , for which you will need to follow the installation instructions here:

https://dotnet.microsoft.com/download/

To install, add the wsl-translinux repository here by issueing the following command, or by following the instructions here (https://packagecloud.io/arkane-systems/wsl-translinux):

curl -s https://packagecloud.io/install/repositories/arkane-systems/wsl-translinux/script.deb.sh | sudo bash

then install genie using the command:

sudo apt install -y systemd-genie

PLEASE NOTE

The wsl-translinux repository is hosted by packagecloud.io, whose free plan allows for 250 MB of downloads per month. Due to the unexpected popularity of genie, we are currently skating right at the edge of this level of usage, and my poor indie developer budget does not stretch to the $75/mo. required for a "Small" plan. As such, if it won't download for you, you may need to either download the .deb file from the Releases page and install manually using dpkg -i, or wait for the usage counter to reset on the 12th of the month.

We apologize for the inconvenience. Anyone wishing to be this project's sugar daddy is welcome to apply.

Other Distros

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

Other

We're actively looking for maintainers for everything else. If you can use .deb packages (especially if your distro is a Debian derivative), the Debian package may work for you. Otherwise, manually installing from the .tar.gz is probably the best I can suggest.

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

...OR BUILD IT YOURSELF

It is possible to build your own version of genie and install it locally. To do so, you will require build-essential and dotnet-sdk-3.1 in addition to the other dependencies, all of which must be installed manually.

After cloning the repository, run

sudo make local

This will build genie and install it under /usr/local .

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), and also the explicit path to unshare(1), required by daemonize(1). Normally, it looks like this:

[genie]
secure-path=/lib/systemd:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
unshare=/usr/bin/unshare
update-hostname=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. Meanwhile, the unshare setting is much more likely to be system-dependent; if you are getting errors running genie, please replace this with the output of which unshare before trying anything else.

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 Insider 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.

USAGE

genie:
  Handles transitions to the "bottle" namespace for systemd under WSL.

Usage:
  genie [options] [command]

Options:
  -v, --verbose <VERBOSE>    Display verbose progress messages
  --version                  Display version information

Commands:
  -i, --initialize           Initialize the bottle (if necessary) only.
  -s, --shell                Initialize the bottle (if necessary), and run a shell in it.
  -c, --command <COMMAND>    Initialize the bottle (if necessary), and run the specified command in it.
  --shutdown, -u             Shut down systemd and exit the bottle.

So, it has three modes, all of which will set up the bottle and run systemd in it if it isn't already running for simplicity of use.

genie -i will set up the bottle - including changing the WSL hostname by suffixing -wsl, to distinguish it from the Windows host - run systemd, and then exit. This is intended for use if you want services running all the time in the background, or to preinitialize things so you needn't worry about startup time later on, and for this purpose is ideally run from Task Scheduler on logon.

genie -s runs your login shell inside the bottle; basically, Windows-side, wsl genie -s is your substitute for just wsl to get started, or for the shortcut you get to start a shell in the distro. It follows login semantics, and as such does not preserve the current working directory.

genie -c [command] runs command inside the bottle, then exits. The return code is the return code of the command. It follows sudo semantics, and so does preserve the cwd.

Meanwhile, genie -u , run from outside the bottle, will shut down systemd cleanly and exit the bottle. This uses the systemctl poweroff command to simulate a normal Linux system shutting down. It is suggested that this be used before shutting down Windows or restarting the Linux distribution to ensure a clean shutdown of systemd services.

While not compulsory, it is recommended that you shut down and restart the WSL distro before using genie again after you have used genie -u. See BUGS, below, for more details.

RECOMMENDATIONS

Once you have this up and running, I suggest disabling via systemctl the getty@tty1 service (since logging on and using WSL is done via ptsen, not ttys).

Further tips on usage from other genie users can be found on the wiki for this repo.

BUGS

1. This breaks pstree and other /proc-walking tools that count on everything being a child of pid 1, because entering the namespace with a shell or other process leaves that process with a ppid of 0. To the best of my knowledge, I can't set the ppid of a process, and if I'm wrong about that, please send edification and pull requests to be gratefully accepted.

2. It is considerably clunkier than I'd like it to be, inasmuch as you have to invoke genie every time to get inside the bottle, either manually (replacing, for example, wsl [command] with wsl genie -c [command]), or by using your own shortcut in place of the one WSL gives you for the distro, using which will put you outside the bottle. Pull requests, etc.

3. There is a race condition that means that if you start a genie session too quickly after initializing the bottle (very likely if you use genie -c or genie -s without having running genie -i first, meaning that they will auto-initialize the bottle on first run), you may not get a systemd-logind login session or the functionality supplied by that, such as a systemd user instance. Using genie -i is strongly recommended to avoid this issue. Please see arkane-systems/genie#70 for more details.

4. genie is not idempotent; i.e., it is possible that changes made by genie or by systemd inside the bottle will not be perftectly reverted when the genie bottle is shut down with genie -u . As such, it is recommended that you terminate the entire wsl session with wsl -t or wsl --shutdown in between stopping and restarting the bottle, or errors may occur.