diff --git a/Makefile b/Makefile index 6846ecd..357726a 100644 --- a/Makefile +++ b/Makefile @@ -3,7 +3,7 @@ # # Bottle-Imp version -IMPVERSION = 0.2 +IMPVERSION = 0.3 # Determine this makefile's path. # Be sure to place this BEFORE `include` directives, if any. diff --git a/binsrc/imp/__main__.py b/binsrc/imp/__main__.py index 297b9ec..093064d 100644 --- a/binsrc/imp/__main__.py +++ b/binsrc/imp/__main__.py @@ -10,7 +10,7 @@ import helpers # Global variables -version = "0.2" +version = "0.3" verbose = False login = None diff --git a/debian/bottle-imp.manpages b/debian/bottle-imp.manpages new file mode 100644 index 0000000..7d180c9 --- /dev/null +++ b/debian/bottle-imp.manpages @@ -0,0 +1 @@ +othersrc/docs/imp.8 \ No newline at end of file diff --git a/debian/changelog b/debian/changelog index 921f6fd..a1b87d8 100644 --- a/debian/changelog +++ b/debian/changelog @@ -1,3 +1,9 @@ +bottle-imp (0.3) bullseye bookworm sid; urgency=medium + + * First (alpha) public version. + + -- Alistair Young Fri, 23 Sep 2022 12:00:00 -0500 + bottle-imp (0.2) bullseye bookworm sid; urgency=medium * Updated dependencies of pstorefs.service. diff --git a/debian/docs b/debian/docs index 9d01b47..20099df 100644 --- a/debian/docs +++ b/debian/docs @@ -1 +1,2 @@ +othersrc/docs/LICENSE.md othersrc/docs/README.md diff --git a/othersrc/docs/README.md b/othersrc/docs/README.md index db69749..61d1a0f 100644 --- a/othersrc/docs/README.md +++ b/othersrc/docs/README.md @@ -1,2 +1,100 @@ # bottle-imp -A spinoff of genie to supplement WSL's new built-in systemd support. + +## A helper for using WSL's native systemd support + +_bottle-imp_ is a spinoff of _[systemd-genie](http://github.com/arkane-systems/genie)_ +to supplement WSL's [new built-in systemd support](https://devblogs.microsoft.com/commandline/systemd-support-is-now-available-in-wsl/). + +**Why is this necessary?** + +Well, awesome as the native _systemd_ support is, there are some things it +doesn't do, and others that it does in notably different ways from _genie_ +or other existing _systemd_ solutions. For more information, you can see my +[migrating from systemd-genie to native WSL systemd](https://randombytes.substack.com/p/migrating-from-systemd-genie-to-native) +article here. + +**What does it do, exactly?** + +The following features are provided by _bottle-imp_ (see the above article for more in-depth explanations): + + * Ensures that _securityfs_ (needed for AppArmor and LSMs) and _pstorefs_ (for debugging panics) are mounted. + * Ensures that the symlink of _/tmp/.X11-unix/X0_, which makes WSLg work, is restored after _systemd_ clears out _/tmp_. + * Ensures that WSL interop is working, even after _systemd_ rebuilds the binfmts. + * Makes sure _systemd_ is up and running before proceeding. + * Mounts the WSLg-created user runtime directory over the _systemd_ user runtime directory, ensuring everything's in the right place. + * Keeps the WSL instance running even when you have no active sessions. + +and the big one + + * Creates a login session for you, along with a user _systemd_ and a session dbus. + +## REQUIREMENTS + +First, obviously, if you were previously a user of _systemd-genie_ or one of the other systemd solutions, uninstall it _before_ attempting to set up native _systemd_ support or _bottle-imp_. + +It is a good idea to set your _systemd_ default target to _multi-user.target_ before enabling systemd native support. TThe 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 microsoft/WSL#423 (comment) - 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". + +Obviously, since native _systemd_ support only works under WSL 2, the same can be said for _imp_. + +Some _systemd_ units were problematic for various reasons under _genie_, and continue to be so under native support. +A list of common problematic units and solutions [is available here](https://randombytes.substack.com/p/problematic-systemd-units-under-wsl). + +## INSTALLATION + +If there is a package available for your distribution, this is the recommended method of installing genie. + +### Debian +Dependent packages on Debian are libc6 (>= 2.34), 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 imp using the commands: + +```bash +sudo apt update +sudo apt install -y imp +``` + +## USAGE + +``` +usage: imp [-h] [-V] [-v] [-a USER] (-i | -s | -l | -c ...) + +Helper for using WSL systemd native support. + +options: + -h, --help show this help message and exit + -V, --version show program's version number and exit + -v, --verbose display verbose progress messages + -a USER, --as-user USER + specify user to run shell or command as (use with -s or -c) + +commands: + -i, --initialize initialize WSL interop for user sessions and hold WSL open until explicit shutdown + -s, --shell open or connect to a systemd user session, and run a shell in it + -l, --login open a login prompt for a systemd user session + -c ..., --command ... + open or connect to a systemd user session, and run the specified command in it (preserves working directory) + +For more information, see https://github.com/arkane-systems/bottle-imp/ +``` + +There are four primary commands available in _bottle-imp_. + +_imp -i_ should be run first to set up your WSL instance. It has two effects (apart from waiting for systemd to be ready); it copies the necessary information to ensure that Windows interoperability works inside systemd-managed login sessions and even services, and it starts a lifetime-running process to ensure that the WSL instance does not terminate even when you have no interactive sessions open. + +**NOTE:** For technical reasons, it is not currently possible to separate these functions; you can't have reliable Windows interop without the lifetime-running process. + +**NOTE 2:** The below commands will still work even if you do not run _imp -i_; however, Windows interop will not function inside systemd-managed sessions, and the WSL instance will idle-terminate as soon as there are no interactive sessions (technically defined as processes that are children of the Microsoft _init_) running. + +_imp -s_ runs your login shell inside a systemd login session; basically, Windows-side, _wsl imp -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. + +_imp -c [command]_ runs _command_ inside a systemd login session, then exits. It follows _sudo_ semantics, and so does preserve the cwd. + +With either of the above, the _imp -a [user]_ option may be used to specify a particular user to start a shell for, or to run a command as, rather than using the currently logged-in user. For example, _imp -a bongo -s_ would start a shell as the user _bongo_. + +_imp -l_ opens a login prompt. This permits you to log in to the WSL distribution via _systemd_ as any user. The login prompt will return when you log out; to terminate the session, press ^] three times within one second. It follows _login_ semantics, and as such does not preserve the current working directory. diff --git a/othersrc/docs/imp.8 b/othersrc/docs/imp.8 new file mode 100644 index 0000000..24f6caa --- /dev/null +++ b/othersrc/docs/imp.8 @@ -0,0 +1,92 @@ +.Dd 09/23/22 +.Dt imp 8 +.Os Linux +.Sh NAME +.Nm imp +.Nd A helper for Windows Subsystem for Linux's native systemd support. +.Sh SYNOPSIS +.Nm +.Op -h +.Op -V +.Op -v +.Op -a +.Ar user +.Op -i +.Op -s +.Op -l +.Op -c +.Ar command... +.Sh DESCRIPTION +.Nm +provides a means of running inside a +.Xr systemd 1 +user session, with full support for user +.Xr systemd 1 +, session dbus, and Windows interoperability. +.Pp +.Bl -tag -width "-c ..., --command ..." +.It Fl h, -help +Prints a short help text and exits. +.It Fl V, -version +Prints the installed imp version and exits. +.It Fl v, -verbose +Causes any other command to print the details of the operations it is +performing as it goes along. Useful mostly for debugging. +.It Fl a, -as-user +Permits a user to be specified (by name) to execute as when using the -c/--command +or -s/--shell commands. +.It Fl i, -initialize +Sets up the needful for Windows interoperability support, and starts the +lifetime-running process to preserve the current WSL instance. It should +be run before any of the other +.Nm +commands. +.It Fl s, -shell +Runs your login shell within a systemd login session. It is intended as +the standard way to start a shell within a distribution with +.Nm +installed. +.Pp +This follows login semantics, and as such does not preserve the current +working directory. +.It Fl l, -login +Opens a login prompt. This permits you to log in to the WSL distribution +as any user. The login prompt will return when you log out; to terminate +the session, press ^] three times within one second. +.Pp +This follows login semantics, and as such does not preserve the current +working directory. +.It Fl c, -command +Runs the specified command inside a systemd login session. It is +intended as the standard way to run arbitrary commands within a +distribution with +.Nm +installed. +.Pp +Unlike the other options, this preserves the current working directory. +.El +.Sh EXIT STATUS +.Nm +maintains a policy of returning zero on success, and non-zero when an error +occurs. +.Sh NOTES +.Nm +can only be used within a WSL 2 distribution, since +.Xr systemd 1 +can only be run within a WSL 2 distribution. WSL 1 does not implement the +system calls required to support it. +.Pp +.Nm +serves no purpose on Linux running outside of the WSL environment, or +within other containers. Its behavior if run in such environments is +undefined. +.Sh SEE ALSO +.Xr systemctl 1 , +.Xr systemd 1 , +.Xr bootup 7 , +.Xr systemd-machined 8 , +.Sh BUGS +If you feel you have found a bug in +.Nm +please submit a bug report at +.Ar http://github.com/arkane-systems/bottle-imp/issues