Waydroid: Difference between revisions
m (Add zh-hans) |
(due to either a regression or misconfiguration in firewalld, the waydroid interface needs to be added to trusted zone Without that, the user won't get the intended "out of the box" internet connection as promised within the article) |
||
(42 intermediate revisions by 21 users not shown) | |||
Line 2: | Line 2: | ||
[[Category:Virtualization]] | [[Category:Virtualization]] | ||
[[Category:Android]] | [[Category:Android]] | ||
[[zh-hans:Waydroid]] | |||
{{Related articles start}} | {{Related articles start}} | ||
{{Related|Linux Containers}} | {{Related|Linux Containers}} | ||
{{Related articles end}} | {{Related articles end}} | ||
{{Style|Need to improve style.}} | {{Style|Need to improve style.}} | ||
Waydroid is a container-based approach to boot a full Android system on a regular GNU/Linux system. | [https://waydro.id Waydroid] is a container-based approach to boot a full Android system on a regular GNU/Linux system. | ||
== Prerequisites == | == Prerequisites == | ||
Line 15: | Line 15: | ||
=== CPU Requirements === | === CPU Requirements === | ||
The requirements depend on the CPU architecture. You can check [https://developer.android.com/ndk/guides/abis#sa table] for more information. | The requirements depend on the CPU architecture. You can check this [https://developer.android.com/ndk/guides/abis#sa table] for more information. | ||
You can check if you have the required CPU instructions with {{ic|cat /proc/cpuinfo}}. | You can check if you have the required CPU instructions with {{ic|cat /proc/cpuinfo}}. | ||
Line 23: | Line 23: | ||
Waydroid currently works best with Intel GPUs. They should work out of the box. | Waydroid currently works best with Intel GPUs. They should work out of the box. | ||
All AMD GPUs have been supported; if Waydroid does | All AMD GPUs have been supported; if Waydroid does not work you might also want to try to build a new Waydroid image (which works for Radeon 680M), or try the NVIDIA instructions below. | ||
NVIDIA GPUs do | NVIDIA GPUs do not work currently, but there are 2 workarounds. | ||
# Switch to integrated graphic card if possible | |||
# Use software rendering (see [[#Software rendering]]) | |||
=== Wayland session manager === | === Wayland session manager === | ||
Line 38: | Line 34: | ||
Waydroid only works in a [[Wayland]] session manager, so make sure you are in a Wayland session. | Waydroid only works in a [[Wayland]] session manager, so make sure you are in a Wayland session. | ||
Note that even if you are in X11, many Wayland session managers support nested session (so you can run it inside your X11 session), the simplest example is {{pkg| | Note that even if you are in X11, many Wayland session managers support nested session (so you can run it inside your X11 session), the simplest example is {{pkg|cage}}. | ||
=== Kernel Modules === | === Kernel Modules === | ||
You need to run a kernel which comes with the binder modules | You need to run a kernel which comes with the binder modules. They are not part of Arch Linux's default kernel ({{Pkg|linux}}), thus you need to install a kernel which ships these modules. | ||
You might also need to configure your bootloader to use a different kernel. Please refer to the wiki page of your bootloader how to boot with the new kernel. Booting into another kernel (version) is one of the few occasions when you have to reboot a Linux system. You should boot into the kernel with these modules before starting Waydroid. | You might also need to configure your bootloader to use a different kernel. Please refer to the wiki page of your bootloader how to boot with the new kernel. Booting into another kernel (version) is one of the few occasions when you have to reboot a Linux system. You should boot into the kernel with these modules before starting Waydroid. | ||
To get a compatible kernel, you have multiple options: | To get a compatible kernel, you have multiple options: | ||
Line 52: | Line 46: | ||
==== Using Linux-Zen ==== | ==== Using Linux-Zen ==== | ||
The {{Pkg|linux-zen}} kernel includes the necessary modules. This might be the most comfortable way, as you do not have to compile the kernel (which takes a long time) and will receive updated versions regularly. | The {{Pkg|linux-zen}} kernel includes the necessary modules, the headers {{Pkg|linux-zen-headers}} are required for {{ic|binder_linux}}. This might be the most comfortable way, as you do not have to compile the kernel (which takes a long time) and will receive updated versions regularly. | ||
==== DKMS modules ==== | ==== DKMS modules ==== | ||
Install {{aur|binder_linux-dkms}} and load the [[kernel module]] {{ic|binder_linux}}. | |||
==== Building a kernel ==== | ==== Building a kernel ==== | ||
Line 114: | Line 104: | ||
Afterwards init Waydroid, this will automatically download the latest Android image if it is not yet available. | Afterwards init Waydroid, this will automatically download the latest Android image if it is not yet available. | ||
# waydroid init | # waydroid init | ||
To init with GApps support: | To init with GApps support: | ||
# waydroid init -s GAPPS | |||
# waydroid init -s GAPPS | |||
Next [[start/enable]] the {{ic|waydroid-container.service}}. | Next [[start/enable]] the {{ic|waydroid-container.service}}. | ||
Line 124: | Line 117: | ||
== Usage == | == Usage == | ||
Make sure that {{ic|waydroid-container.service}} is | Make sure that {{ic|waydroid-container.service}} is [[start]]ed then run: | ||
$ waydroid session start | $ waydroid session start | ||
Line 130: | Line 124: | ||
''Launch GUI'': | ''Launch GUI'': | ||
$ waydroid show-full-ui | $ waydroid show-full-ui | ||
''Launch shell'': | ''Launch shell'': | ||
# waydroid shell | # waydroid shell | ||
''Install an application'': | ''Install an application'': | ||
$ waydroid app install $path_to_apk | $ waydroid app install $path_to_apk | ||
''Run an application'': | ''Run an application'': | ||
$ waydroid app launch $ | |||
$ waydroid app launch $package_name # Can be retrieved with `waydroid app list` | |||
== Network == | == Network == | ||
Line 144: | Line 145: | ||
Taking {{pkg|ufw}} as an example: | Taking {{pkg|ufw}} as an example: | ||
* | * DNS traffic needs to be allowed: | ||
** {{bc|# ufw allow 67}} | ** {{bc|# ufw allow 67}} | ||
** {{bc|# ufw allow 53}} | ** {{bc|# ufw allow 53}} | ||
Line 157: | Line 158: | ||
* Packet forwarding: | * Packet forwarding: | ||
** {{bc|1=# firewall-cmd --zone=trusted --add-forward}} | ** {{bc|1=# firewall-cmd --zone=trusted --add-forward}} | ||
* Add the waydroid interface to a trusted: | |||
** {{bc|1=# firewall-cmd --zone=trusted --add-interface=waydroid0}} | |||
{{Note|We assume that interface {{ic|waydroid0}} created by waydroid should be in the firewalld zone {{ic|trusted}} automatically. If not so, please adjust those commands above or move interface {{ic|waydroid0}} to {{ic|trusted}}. You may also need {{bc|# firewall-cmd --runtime-to-permanent}} to make your changes | {{Note|We assume that interface {{ic|waydroid0}} created by waydroid should be in the firewalld zone {{ic|trusted}} automatically. If not so, please adjust those commands above or move interface {{ic|waydroid0}} to {{ic|trusted}}. You may also need {{bc|# firewall-cmd --runtime-to-permanent}} to make your changes persist after a restart.}} | ||
== Tips and tricks == | |||
=== Software rendering === | |||
Make sure that you have already run: | |||
# waydroid init | |||
(see [[#Installation]] section for more information) | |||
Then, add the following: | |||
{{hc|/var/lib/waydroid/waydroid_base.prop|<nowiki> | |||
ro.hardware.gralloc=default | |||
ro.hardware.egl=swiftshader | |||
</nowiki>}} | |||
Finally, [[restart]] the {{ic|waydroid-container.service}}. | |||
=== Setting viewport dimensions === | |||
To set the dimensions of the waydroid window use the following commands with the dimensions adjusted to your liking: | |||
$ waydroid prop set persist.waydroid.width 576 | |||
$ waydroid prop set persist.waydroid.height 1024 | |||
Then [[restart]] the {{ic|waydroid-container.service}}. | |||
== Troubleshooting == | == Troubleshooting == | ||
If you run into issues, take a look at the official Issue Tracker: [https://github.com/waydroid/waydroid/issues Waydroid issue tracker] | If you run into issues, take a look at the official Issue Tracker: [https://github.com/waydroid/waydroid/issues Waydroid issue tracker]. | ||
=== General tips === | === General tips === | ||
Waydroid is in rapid | Waydroid is in rapid development so if you face issues, here is a good list of steps to do first: | ||
# Make sure your Waydroid package is up to date | # Make sure your Waydroid package is up to date. | ||
# Make sure you have the latest Waydroid image by running {{bc|# waydroid upgrade}} | # Make sure you have the latest Waydroid image by running {{bc|# waydroid upgrade}} | ||
# Reset Waydroid: [[stop]] the {{ic|waydroid-container.service}}, run {{bc|# waydroid init -f}} and [[start]] the service again. | # Reset Waydroid: [[stop]] the {{ic|waydroid-container.service}}, run {{bc|# waydroid init -f}} and [[start]] the service again. | ||
# You may also want to do little cleanup, run {{bc|# rm -rf /var/lib/waydroid /home/.waydroid}} {{bc|$ rm -rf ~/waydroid ~/.share/waydroid ~/.local/share/applications/*aydroid* ~/.local/share/waydroid}} | # You may also want to do little cleanup, run {{bc|# rm -rf /var/lib/waydroid /home/.waydroid}} {{bc|$ rm -rf ~/waydroid ~/.share/waydroid ~/.local/share/applications/*aydroid* ~/.local/share/waydroid}} | ||
::{{Tip|Removing {{ic|/home/.waydroid/}} is unnecessary if you installed it after [https://github.com/waydroid/waydroid/commit/eef036b3f814a9fc4869ebfe6c9d2bd51fa19f26 2021-09].}} | |||
=== ARM Apps Incompatible === | |||
Use casualsnek's [https://github.com/casualsnek/waydroid_script script] to install a translation layer. | |||
Due to optimizations in the translation layers, It is recommended to use libndk on AMD CPUs and libhoudini on Intel CPUs. However some apps will work on one translation layer and not another. so you may need to try both if a game does not work or gets bad performance. | |||
''Install libndk arm translation'' | |||
# python3 main.py install libndk | |||
''Install libhoudini arm translation'' | |||
# python3 main.py install libhoudini | |||
=== Rotated apps are unusable === | === Rotated apps are unusable === | ||
See https://github.com/waydroid/waydroid/issues/70 | See [https://github.com/waydroid/waydroid/issues/70 Issue 70]. | ||
Click ''F11'' to switch the current app to windowed mode. | Click ''F11'' to switch the current app to windowed mode. | ||
Line 181: | Line 228: | ||
=== Failed to start Clipboard manager service === | === Failed to start Clipboard manager service === | ||
Install {{aur|python-pyclip}} | Install {{aur|python-pyclip}}. | ||
=== Sometimes the physical keyboard does not work === | === Sometimes the physical keyboard does not work === | ||
Press | Press the left {{ic|Alt}} key. | ||
=== | === dnsmasq: failed to open pidfile /run/waydroid-lxc/dnsmasq.pid: Permission denied === | ||
An AppArmor rule is likely not set. Add the following rule: | |||
{{hc|/etc/apparmor.d/usr.sbin.dnsmasq| | |||
@{run}/waydroid-lxc/ r, | @{run}/waydroid-lxc/ r, | ||
@{run}/waydroid-lxc/* rw, }} | @{run}/waydroid-lxc/* rw, | ||
}} | |||
=== Commands inside Waydroid shell outputs inaccessible or not found === | === Commands inside Waydroid shell outputs inaccessible or not found === | ||
On Arch based distributions there's a [[Linux Containers#Basic usage|"bug" that may appear while working with lxc-attach]] that may cause this issue with commands inside {{ic|waydroid shell}} like {{ic|adbd}} or {{ic|settings}}. | On Arch based distributions there's a [[Linux Containers#Basic usage|"bug" that may appear while working with lxc-attach]] that may cause this issue with commands inside {{ic|waydroid shell}} like {{ic|adbd}} or {{ic|settings}}. | ||
A possible workaround for this would be replace the {{ | |||
A possible workaround for this would be replace the {{ic|waydroid shell}} command with | |||
# lxc-attach -P /var/lib/waydroid/lxc/ -n waydroid --clear-env | |||
=== WARNING: Service manager /dev/binder has died === | === WARNING: Service manager /dev/binder has died === | ||
See https://github.com/waydroid/waydroid/issues/136 | See [https://github.com/waydroid/waydroid/issues/136 Issue 136]. | ||
You should enable [https://docs.kernel.org/accounting/psi.html PSI]. | You should enable [https://docs.kernel.org/accounting/psi.html PSI]. | ||
Add {{ic|1=psi=1}} to the [[kernel command line]]. | Add {{ic|1=psi=1}} to the [[kernel command line]]. | ||
=== Graphical Corruption on multi-gpu systems === | |||
Currently Waydroid needs to run on the same GPU the host compositor is running on. The two ways of fixing this is to either edit {{ic|/var/lib/waydroid/lxc/waydroid/config_nodes}} to be the correct GPU or to change the GPU the compositor runs on. | |||
== See also == | == See also == | ||
Line 212: | Line 266: | ||
* [https://github.com/waydroid/waydroid Waydroid GitHub repo] | * [https://github.com/waydroid/waydroid Waydroid GitHub repo] | ||
* [https://docs.waydro.id/ Waydroid documentation] | * [https://docs.waydro.id/ Waydroid documentation] | ||
* [https://matrix.to/#/#waydroid: | * [https://matrix.to/#/#waydroid:matrix.org Waydroid Matrix group] | ||
* [https://t.me/WayDroid Waydroid Telegram group] | * [https://t.me/WayDroid Waydroid Telegram group] |
Latest revision as of 13:59, 12 April 2024
Waydroid is a container-based approach to boot a full Android system on a regular GNU/Linux system.
Prerequisites
CPU Requirements
The requirements depend on the CPU architecture. You can check this table for more information.
You can check if you have the required CPU instructions with cat /proc/cpuinfo
.
GPU Requirements
Waydroid currently works best with Intel GPUs. They should work out of the box.
All AMD GPUs have been supported; if Waydroid does not work you might also want to try to build a new Waydroid image (which works for Radeon 680M), or try the NVIDIA instructions below.
NVIDIA GPUs do not work currently, but there are 2 workarounds.
- Switch to integrated graphic card if possible
- Use software rendering (see #Software rendering)
Wayland session manager
Waydroid only works in a Wayland session manager, so make sure you are in a Wayland session.
Note that even if you are in X11, many Wayland session managers support nested session (so you can run it inside your X11 session), the simplest example is cage.
Kernel Modules
You need to run a kernel which comes with the binder modules. They are not part of Arch Linux's default kernel (linux), thus you need to install a kernel which ships these modules.
You might also need to configure your bootloader to use a different kernel. Please refer to the wiki page of your bootloader how to boot with the new kernel. Booting into another kernel (version) is one of the few occasions when you have to reboot a Linux system. You should boot into the kernel with these modules before starting Waydroid.
To get a compatible kernel, you have multiple options:
Using Linux-Zen
The linux-zen kernel includes the necessary modules, the headers linux-zen-headers are required for binder_linux
. This might be the most comfortable way, as you do not have to compile the kernel (which takes a long time) and will receive updated versions regularly.
DKMS modules
Install binder_linux-dkmsAUR and load the kernel module binder_linux
.
Building a kernel
Alternatively, you can recompile the linux kernel — or other kernel packages (>=5.7) — with the necessary options. Also see Kernel#Compilation.
When setting compilation options, you have 2 options available; binder and binderfs. Instructions for both are provided below.
Using binder
The modules can either be compiled into the kernel (y
), into modules (m
), or not at all (n
). Also, not all combinations in the configuration are possible, and some options will require other options.
The configuration options below will compile binder as a module, while the last option specifies that there will be three devices created in the /dev/
directory, when the binder module is loaded.
CONFIG_ANDROID=y CONFIG_ANDROID_BINDER_IPC=m CONFIG_ANDROID_BINDERFS=n CONFIG_ANDROID_BINDER_DEVICES="binder,hwbinder,vndbinder"
When building a kernel from the AUR, one can update the configuration with the following steps:
- run
makepkg --nobuild
, which will download the sources, verify and extract them and run theprepare()
function. - edit the
.config
file (with the dot in the filename), which is located at the base of the kernel directory. - at the end of the
prepare()
function was probably a command which regenerates the makefiles with information from the configuration, possiblymake olddefconfig
. Move that to thebuild()
function, or execute it yourself. - run
makepkg --noextract
, which will continue from the place wheremakepkg --nobuild
stopped.
Using binderfs
The binder kernel module is known to cause some issues to several users. To address these issues, binderfs was created. One has to choose between the old and the new way when compiling the kernel. With the options below, one will use binderfs instead.
With the kernel sources comes also a simple script to set configuration options. It will not do dependency checks, just like when editing the configuration by hand. When being in the same directory where the .config
file lies, one can execute the following commands:
$ scripts/config --enable CONFIG_ANDROID $ scripts/config --enable CONFIG_ANDROID_BINDER_IPC $ scripts/config --enable CONFIG_ANDROID_BINDERFS $ scripts/config --set-str CONFIG_ANDROID_BINDER_DEVICES ""
When building a kernel from the AUR, it is enough to insert these lines at the right place in the PKGBUILD, usually in prepare()
.
Setup binder devices
Make sure you have the latest version of Waydroid package, and Waydroid will take automatically care of this.
Installation
Install the waydroidAUR package.
Optionally, install waydroid-imageAUR or waydroid-image-gappsAUR to provide the needed Android image through AUR. It is however recommended to let Waydroid itself handle downloading the images.
Afterwards init Waydroid, this will automatically download the latest Android image if it is not yet available.
# waydroid init
To init with GApps support:
# waydroid init -s GAPPS
Next start/enable the waydroid-container.service
.
Waydroid should now work.
Usage
Make sure that waydroid-container.service
is started then run:
$ waydroid session start
The Waydroid session is now active, here are a couple of useful commands to interact with it:
Launch GUI:
$ waydroid show-full-ui
Launch shell:
# waydroid shell
Install an application:
$ waydroid app install $path_to_apk
Run an application:
$ waydroid app launch $package_name # Can be retrieved with `waydroid app list`
Network
The network should work out of the box, if its not you might need to make sure packet forwarding is enabled in kernel and allow the following rules through your firewall before running Waydroid session start.
Taking ufw as an example:
- DNS traffic needs to be allowed:
# ufw allow 67
# ufw allow 53
- Packet forwarding needs to be allowed:
# ufw default allow FORWARD
For firewalld, you can use those commands:
- DNS:
# firewall-cmd --zone=trusted --add-port=67/udp
# firewall-cmd --zone=trusted --add-port=53/udp
- Packet forwarding:
# firewall-cmd --zone=trusted --add-forward
- Add the waydroid interface to a trusted:
# firewall-cmd --zone=trusted --add-interface=waydroid0
waydroid0
created by waydroid should be in the firewalld zone trusted
automatically. If not so, please adjust those commands above or move interface waydroid0
to trusted
. You may also need # firewall-cmd --runtime-to-permanentto make your changes persist after a restart.
Tips and tricks
Software rendering
Make sure that you have already run:
# waydroid init
(see #Installation section for more information)
Then, add the following:
/var/lib/waydroid/waydroid_base.prop
ro.hardware.gralloc=default ro.hardware.egl=swiftshader
Finally, restart the waydroid-container.service
.
Setting viewport dimensions
To set the dimensions of the waydroid window use the following commands with the dimensions adjusted to your liking:
$ waydroid prop set persist.waydroid.width 576 $ waydroid prop set persist.waydroid.height 1024
Then restart the waydroid-container.service
.
Troubleshooting
If you run into issues, take a look at the official Issue Tracker: Waydroid issue tracker.
General tips
Waydroid is in rapid development so if you face issues, here is a good list of steps to do first:
- Make sure your Waydroid package is up to date.
- Make sure you have the latest Waydroid image by running
# waydroid upgrade
- Reset Waydroid: stop the
waydroid-container.service
, run# waydroid init -f
and start the service again. - You may also want to do little cleanup, run
# rm -rf /var/lib/waydroid /home/.waydroid
$ rm -rf ~/waydroid ~/.share/waydroid ~/.local/share/applications/*aydroid* ~/.local/share/waydroid
- Tip: Removing
/home/.waydroid/
is unnecessary if you installed it after 2021-09.
ARM Apps Incompatible
Use casualsnek's script to install a translation layer.
Due to optimizations in the translation layers, It is recommended to use libndk on AMD CPUs and libhoudini on Intel CPUs. However some apps will work on one translation layer and not another. so you may need to try both if a game does not work or gets bad performance.
Install libndk arm translation
# python3 main.py install libndk
Install libhoudini arm translation
# python3 main.py install libhoudini
Rotated apps are unusable
See Issue 70.
Click F11 to switch the current app to windowed mode.
Failed to start Clipboard manager service
Install python-pyclipAUR.
Sometimes the physical keyboard does not work
Press the left Alt
key.
dnsmasq: failed to open pidfile /run/waydroid-lxc/dnsmasq.pid: Permission denied
An AppArmor rule is likely not set. Add the following rule:
/etc/apparmor.d/usr.sbin.dnsmasq
@{run}/waydroid-lxc/ r, @{run}/waydroid-lxc/* rw,
Commands inside Waydroid shell outputs inaccessible or not found
On Arch based distributions there's a "bug" that may appear while working with lxc-attach that may cause this issue with commands inside waydroid shell
like adbd
or settings
.
A possible workaround for this would be replace the waydroid shell
command with
# lxc-attach -P /var/lib/waydroid/lxc/ -n waydroid --clear-env
WARNING: Service manager /dev/binder has died
See Issue 136.
You should enable PSI.
Add psi=1
to the kernel command line.
Graphical Corruption on multi-gpu systems
Currently Waydroid needs to run on the same GPU the host compositor is running on. The two ways of fixing this is to either edit /var/lib/waydroid/lxc/waydroid/config_nodes
to be the correct GPU or to change the GPU the compositor runs on.