Unl0kr

An issue with upstream unl0kr causes it to fail to run properly on some devices running v23.06 (stable). Be sure to make sure that your device works with it before switching to unl0kr on v23.06.

Unl0kr is a disk unlocker UI replacing Osk-sdl. It is written in C using LVGL and runs on the Linux framebuffer without hardware acceleration.

By itself unl0kr doesn't actually perform any unlocking. Instead it uses the so called "keyscript mode" in which the entered password is piped through STDOUT into the actual unlocking program. The unl0kr package in pmOS's aports implements the latter as a shell script.

Installation

Unl0kr conflicts with osk-sdl and you won't be able to install both at the same time

The unl0kr package is part of pmOS's aports directory. When installing pmOS, you can select unl0kr over osk-sdl via

$ pmbootstrap install --fde --add unl0kr

Alternatively, you may also install unl0kr into a running system with apk. Installing the package automatically triggers regeneration of the initramfs.

Running outside the initramfs

For testing purposes, you can run unl0kr outside the boot process. Simply switch to a TTY (e.g. with chvt) and run

$ sudo unl0kr

As mentioned above, unl0kr only prints the entered password to STDOUT so this won't actually do anything to your disks.

Configuration

Unl0kr's configuration file resides in /etc/unl0kr.conf. There is currently no documentation for the existing options but you may refer to the unl0kr/unl0kr.conf for inspiration.

Among others, a number of built-in UI themes can be selected through the config file. For screenshots of the currently available themes see unl0kr/screenshots.

To verify the effect of changing config options, you can run unl0kr manually from a TTY as described in the "Running outside the initramfs" section. To actually apply the changes during boot, you need to regenerate the initramfs.

Issues with DRM/MSM fbdev emulation

Some devices with DRM/MSM fbdev emulation enabled in the kernel (via CONFIG_DRM_SIMPLEDRM) will fail to re-render and update the unl0kr GUI (sometimes not even drawing it on boot). It is possible to apply a workaround in unl0kr.conf:

[quirks]
fbdev_force_refresh=true

See this issue for further discussion and pmaports!4447 for adding a config for oneplus-enchilada.

Troubleshooting

The initramfs environment in which unl0kr runs during boot is notably different from your normal system environment. Therefore, the first step in verifying whether unl0kr works on your system is to run it outside the initramfs as described in the "Running outside the initramfs" section. If it doesn't work there, it won't work during boot either.

If you've verified that unl0kr runs outside the initramfs but it still fails during boot, you can use the debug-shell to debug the initramfs environment.

Input devices are not working

The debug-shell ships with several tools you may use for debugging input devices. Unl0kr uses libinput which relies on udev and wraps around the input device handling provided by evdev / the kernel.

As a first step, you can use evtest to list and test the input devices made available by the kernel. If your devices don't show up here, your kernel likely isn't configured correctly.

Afterwards, to verify that the devices have been set up correctly for use with libinput, you can use the eponymous program.

$ libinput list-devices
Device:           ZSA Technology Labs Inc ErgoDox EZ
Kernel:           /dev/input/event0
Group:            7
Seat:             seat0, default
Capabilities:     keyboard 
Tap-to-click:     n/a
Tap-and-drag:     n/a
Tap drag lock:    n/a
Left-handed:      n/a
Nat.scrolling:    n/a
Middle emulation: n/a
Calibration:      n/a
Scroll methods:   none
Click methods:    none
Disable-w-typing: n/a
Accel profiles:   n/a
Rotation:         n/a
...
$ libinput debug-events
-event0   DEVICE_ADDED            ZSA Technology Labs Inc ErgoDox EZ seat0 default group7  cap:k
...
-event0   KEYBOARD_KEY            +0.000s      *** (-1) pressed
 event0   KEYBOARD_KEY            +0.008s      *** (-1) released
 event0   KEYBOARD_KEY            +0.776s      *** (-1) pressed
 event0   KEYBOARD_KEY            +0.784s      *** (-1) released
...

If your devices don't show up here, you might be missing udev rules to make them work correctly.

Unlocking via telnet

If Unl0kr does not work for some reason , but you really need to access your data, you can connect to the initramfs via telnet, enable initramfs-extra, then run the following to unlock it:

# source /init_functions.sh
# cryptsetup luksOpen "$(find_root_partition)" root
Enter passphrase for /dev/mapper/mmcblk0p2:
# killall unl0kr

Reporting issues

Issues with unl0kr should be reported on the project's GitLab issues page.

There is currently no dedicated Matrix room but if needed you may contact @h3nn3s:matrix.org directly.