Jump to content

Anbox: Difference between revisions

From postmarketOS Wiki
Afontain (talk | contribs)
m this is already mentioned in the porting guide
update to gitlab.postmarketos.org
 
(17 intermediate revisions by 7 users not shown)
Line 1: Line 1:
{{note|'''Anbox has been removed from postmarketOS v21.12 and newer in favor of [[Waydroid]].'''}}
{{note|Consider using native Linux programs instead, see [[FAQ]].}}
{{note|Consider using native Linux programs instead, see [[FAQ]].}}
{{note|Development on this feature can be done without running pmOS on a real device with [[QEMU]]. Please use the lts kernel for that as the virt kernel doesn't include the necessary modules.}}
{{note|Development on this feature can be done without running pmOS on a real device with [[QEMU]]. Please use the <code>lts</code> kernel for that as the virt kernel doesn't include the necessary modules. You will likely need to pass the <code>-m2048</code> flag as the default 1GB will not be enough.}}
{{note|Anbox is currently somewhat broken on armv7 because Anbox assumes 64 bits in some places, which breaks input (see https://github.com/anbox/anbox/issues/1214#issuecomment-524578664. Please manifest yourself if you can test and try that)}}
{{note|Anbox is currently somewhat broken on armv7 because Anbox assumes 64 bits in some places, which breaks input (see https://github.com/anbox/anbox/issues/1214#issuecomment-524578664. Please manifest yourself if you can test and try that)}}


Line 7: Line 8:
'''[https://anbox.io Anbox]''' runs Android apps on Linux using a trimmed down version of Android in a container. Anbox allows one to use Android applications sandboxed, running alongside the native Linux programs. It can be very handy to help people switch from Android to an operating that respects their privacy.
'''[https://anbox.io Anbox]''' runs Android apps on Linux using a trimmed down version of Android in a container. Anbox allows one to use Android applications sandboxed, running alongside the native Linux programs. It can be very handy to help people switch from Android to an operating that respects their privacy.


See {{milestone|7}} for current progress.
See [https://gitlab.postmarketos.org/postmarketOS/pmaports/-/issues?scope=all&utf8=%E2%9C%93&state=all&label_name%5B%5D=Anbox the Anbox label in the issue tracker] for current progress.


== Installation ==
== Installation ==


Install the <code>postmarketos-anbox</code> package. Launch using <code>anbox-launch</code> or the icon launcher.
Install the <code>postmarketos-anbox</code> package, which pulls in anbox and the anbox image required to run it. Then start the <code>anbox-container-manager</code> service. Anbox takes several minutes to start up, and after the initial start, a lot of new desktop icons from Android should appear (Calendar, Clock, Contacts, F-Droid, Email, Files, ...).


<syntaxhighlight lang="shell-session">
$ sudo apk add postmarketos-anbox
$ sudo rc-service anbox-container-manager start
</syntaxhighlight>


== Porting ==
== Tips and Tricks ==
 
=== Factory reset ===
 
You can delete all data known by Anbox, effectively doing the equivalent of a factory reset for physical Android devices. To do that, stop the anbox service using <code>sudo rc-service anbox-container-manager stop</code> and remove everything in <code>/var/lib/anbox/</code>.
 
=== Virtual keyboard input in Phosh ===


=== Requirements ===
Keyboard input is currently broken in Phosh because of some [https://source.puri.sm/Librem5/squeekboard/-/issues/218 bugs] in squeekboard. Previously a workaround was to use virtboard instead of squeekboard, however nowadays that package isn't available anymore.


You need a few things to get started with porting Anbox support to your device:
=== Workaround for Anbox content being covered by Phosh' bottom bar ===


* '''device with mainline postmarketOS kernel support'''
$ adb shell wm overscan 0,0,0,70


Since Anbox require DRI to function, you need mainline kernel to get it to work.
You may need to adjust the dimensions depending on your device. These should work well for the PinePhone.


* '''Linux environment'''
== Porting ==


pmbootstrap needs Linux environment to function, and porting process may also require rebuilding the kernel.
=== Requirements ===
 
* More than 1GB of RAM. Anbox is known to be broken on 512MB of RAM and has a lot of issues with 1GB. It is known to work well on 2GB (pinephone).
 
* Kernel v3.17+ or alternatively one with the <code>memfd_create</code> syscall available (required by LXC).


=== Checking defconfig ===
=== Checking defconfig ===


First, you need to know which kernel package does your device use to perform a kconfig check(replace wiki-example with your actual device codename):
First, you need to know which kernel package does your device use to perform a kconfig check (replace wiki-example with your actual device codename):


<syntaxhighlight lang="shell-session">
<syntaxhighlight lang="shell-session">
Line 71: Line 86:
Anbox require an anbox0 bridge interface to access the internet. <code>ip link</code> should report an anbox0 interface for the network to work. There seem to be some kind of kernel requirement too, see {{Issue|480|pmaports}} (contains workaround) for the investigation about that.
Anbox require an anbox0 bridge interface to access the internet. <code>ip link</code> should report an anbox0 interface for the network to work. There seem to be some kind of kernel requirement too, see {{Issue|480|pmaports}} (contains workaround) for the investigation about that.


=== When I start Anbox, it complains about DBus ===
=== <code>The name org.anbox was not provided by any .service files</code> ===
 
This error usually means the <code>anbox session-manager</code> command crashed. Launch it manually to see the actual error message.
 
=== <code>Failed to request DBus service name</code> ===
 
This error means dbus isn't running, or that you launched it incorrectly (check environment variables are set with <code>env</code>). Ensure you [https://gitlab.postmarketos.org/postmarketOS/pmaports/issues/458 start dbus with your session] and that you are not starting Anbox with ssh.
 
=== <code>Failed to select EGL configuration</code> ===


<code>[daemon.cpp:61@Run] Failed to request DBus service name</code> means dbus isn't running, or that you launched it incorrectly (check environment variables are set with <code>env</code>). Ensure you [https://gitlab.com/postmarketOS/pmaports/issues/458 start dbus with your session] and that you are not starting Anbox with ssh.
You can try to run the session-manager as such: <code>EGL_PLATFORM=x11 SDL_VIDEODRIVER=x11 anbox session-manager</code>. You need to leave it running and click on the anbox icon to start the GUI.




Line 95: Line 118:


In this case, tell me in a bug report that '''the container ''itself'' doesn't run''' and include <code>/var/lib/anbox/logs/container.log</code>.
In this case, tell me in a bug report that '''the container ''itself'' doesn't run''' and include <code>/var/lib/anbox/logs/container.log</code>.
=== Check the session-manager starts correctly ===
From times to times, the session-manager will segfault or error out. You may want to check [[Anbox#Failed_to_select_EGL_configuration|EGL Configuration]]. In any case open a bug report saying that '''the session-manager fails to start''' and include the output from the command, <code>/var/lib/anbox/logs/container.log</code> and  <code>/var/lib/anbox/logs/container.log</code>.


=== Check if <code>adb</code> works ===
=== Check if <code>adb</code> works ===
Line 104: Line 131:
Download an apk, for example the [https://f-droid.org/FDroid.apk F-Droid one] and try to install it. For example, <code>adb install Dowloads/FDroid.apk</code>. If this doesn't work, then Zygote probably didn't start. If you can get a shell, but can't install an app with adb, tell me in a bug report that '''''adb install'' doesn't work''' and include <code>/var/lib/anbox/logs/console.log</code>.
Download an apk, for example the [https://f-droid.org/FDroid.apk F-Droid one] and try to install it. For example, <code>adb install Dowloads/FDroid.apk</code>. If this doesn't work, then Zygote probably didn't start. If you can get a shell, but can't install an app with adb, tell me in a bug report that '''''adb install'' doesn't work''' and include <code>/var/lib/anbox/logs/console.log</code>.


If <code>adb install</code> works, congratulations, we have only got Anbox to run that far once or twice so far. Please still open an issue if you don't get the anbox application manager to show up, including <code>/var/lib/anbox/logs/console.log</code>.
If <code>adb install</code> works, congratulations. Please still open an issue if you don't get the anbox application manager to show up, including <code>/var/lib/anbox/logs/console.log</code>.


[[Category:Technical Reference]]
[[Category:Technical Reference]]

Latest revision as of 07:39, 3 November 2024

Note Anbox has been removed from postmarketOS v21.12 and newer in favor of Waydroid.
Note Consider using native Linux programs instead, see FAQ.
Note Development on this feature can be done without running pmOS on a real device with QEMU. Please use the lts kernel for that as the virt kernel doesn't include the necessary modules. You will likely need to pass the -m2048 flag as the default 1GB will not be enough.
Note Anbox is currently somewhat broken on armv7 because Anbox assumes 64 bits in some places, which breaks input (see https://github.com/anbox/anbox/issues/1214#issuecomment-524578664. Please manifest yourself if you can test and try that)
The anbox application manager with the default apps.

Anbox runs Android apps on Linux using a trimmed down version of Android in a container. Anbox allows one to use Android applications sandboxed, running alongside the native Linux programs. It can be very handy to help people switch from Android to an operating that respects their privacy.

See the Anbox label in the issue tracker for current progress.

Installation

Install the postmarketos-anbox package, which pulls in anbox and the anbox image required to run it. Then start the anbox-container-manager service. Anbox takes several minutes to start up, and after the initial start, a lot of new desktop icons from Android should appear (Calendar, Clock, Contacts, F-Droid, Email, Files, ...).

$ sudo apk add postmarketos-anbox
$ sudo rc-service anbox-container-manager start

Tips and Tricks

Factory reset

You can delete all data known by Anbox, effectively doing the equivalent of a factory reset for physical Android devices. To do that, stop the anbox service using sudo rc-service anbox-container-manager stop and remove everything in /var/lib/anbox/.

Virtual keyboard input in Phosh

Keyboard input is currently broken in Phosh because of some bugs in squeekboard. Previously a workaround was to use virtboard instead of squeekboard, however nowadays that package isn't available anymore.

Workaround for Anbox content being covered by Phosh' bottom bar

$ adb shell wm overscan 0,0,0,70

You may need to adjust the dimensions depending on your device. These should work well for the PinePhone.

Porting

Requirements

  • More than 1GB of RAM. Anbox is known to be broken on 512MB of RAM and has a lot of issues with 1GB. It is known to work well on 2GB (pinephone).
  • Kernel v3.17+ or alternatively one with the memfd_create syscall available (required by LXC).

Checking defconfig

First, you need to know which kernel package does your device use to perform a kconfig check (replace wiki-example with your actual device codename):

$ cd $(pmbootstrap config aports)
$ cat device/testing/device-wiki-example/APKBUILD | grep linux

The output of the last command will be like this: depends="linux-postmarketos-wiki-example mesa-git-dri-gallium". Your mainline Linux package name will be similar to the highlighted sample one.

Then you need to verify the defconfig with pmbootstrap to make sure all the kernel modules Anbox require will be installed(replace linux-postmarketos-wiki-example with actual kernel package name).

$ pmbootstrap kconfig check --anbox linux-postmarketos-wiki-example

If the check was successful, pmbootstrap will output kconfig check succeeded!. If the check is successful, you can install the postmarketos-anbox package and run anbox-launch to start Anbox.

If some checks failed, you need to rebuild the kernel package with updated defconfig. Update the defconfig so pmbootstrap kconfig check --anbox command will output kconfig check succeeded!.

Updating defconfig

First, you need to bump pkgrel of your kernel package:

$ pmbootstrap pkgrel_bump linux-postmarketos-wiki-example

Then, use pmbootstrap kconfig edit linux-postmarketos-wiki-example to edit the defconfig. You can browse the options menu with arrow keys and select options with Space key. You can also search your needed kconfig option with "/" button.

Once done, close the menuconfig with exit button on bottom. pmbootstrap will update your kernel defconfig and you'll be able to build the kernel.

Try building the kernel with pmbootstrap build linux-postmarketos-wiki-example. If build succeeds, flash the kernel into your device pmbootstrap install && pmbootstrap flasher flash_kernel, and install Anbox.

Once you confirmed that your port is working, edit the kernel package APKBUILD options property to include pmb:kconfigcheck-anbox option(needed to get the package merged) and create new MR to pmaports.

Troubleshooting

I don't have access to the internet

Anbox require an anbox0 bridge interface to access the internet. ip link should report an anbox0 interface for the network to work. There seem to be some kind of kernel requirement too, see pmaports#480 (contains workaround) for the investigation about that.

The name org.anbox was not provided by any .service files

This error usually means the anbox session-manager command crashed. Launch it manually to see the actual error message.

Failed to request DBus service name

This error means dbus isn't running, or that you launched it incorrectly (check environment variables are set with env). Ensure you start dbus with your session and that you are not starting Anbox with ssh.

Failed to select EGL configuration

You can try to run the session-manager as such: EGL_PLATFORM=x11 SDL_VIDEODRIVER=x11 anbox session-manager. You need to leave it running and click on the anbox icon to start the GUI.


Serious Debugging

If you never see the application manager, there can be plenty of problems. The first step to debug this is knowing roughly where it fails.

Check the openRC service

rc-service anbox-container-manager status will give you the state of the container manager. If it reports to be stopped despite your attempts to start it, then the container manager exited. Tell me that the container manager doesn't run in a bug report and include /var/lib/anbox/logs/container.log.

Check if the container is up

If the container manager runs, it doesn't necessarily means the container android runs in is started. To check if the container is up and running, you can try two things can give interesting clues:

using anbox session-manager
check what it answers when you run it. Failed to start container is a pretty obvious way to tell the container doesn't run; but sometimes the session manager will segfault instead. You usually can still tell if container is started.
using /var/lib/anbox/logs/container.log
the file will (hopefully) contain a non-empty log. Look for Received container state "ABORTING" instead of "RUNNING" or Set container state to "STOPPED".

In this case, tell me in a bug report that the container itself doesn't run and include /var/lib/anbox/logs/container.log.

Check the session-manager starts correctly

From times to times, the session-manager will segfault or error out. You may want to check EGL Configuration. In any case open a bug report saying that the session-manager fails to start and include the output from the command, /var/lib/anbox/logs/container.log and /var/lib/anbox/logs/container.log.

Check if adb works

Install android-tools and run adb shell. If you do have a shell, that's great, Android at least started to start. If adb answers you that no devices/emulators are found and the container is running, then tell me in a bug report that adb couldn't find the device and include /var/lib/anbox/logs/console.log.

Check if adb install works

Download an apk, for example the F-Droid one and try to install it. For example, adb install Dowloads/FDroid.apk. If this doesn't work, then Zygote probably didn't start. If you can get a shell, but can't install an app with adb, tell me in a bug report that adb install doesn't work and include /var/lib/anbox/logs/console.log.

If adb install works, congratulations. Please still open an issue if you don't get the anbox application manager to show up, including /var/lib/anbox/logs/console.log.