ADEB

adeb (also known as androdeb) provides a powerful Linux shell environment where one can run popular and mainstream Linux tracing, compiling, editing and other development tools on an existing Android device. All the commands typically available on a modern Linux system are supported in adeb.

The adeb project installs a chroot environment on your Android device to help debugging.

This article shows how to install and use adeb with an 32-bit ARM device to help debugging SELinux denial.

For that purpose the BCC tool trace is used (see a list of BCC tools available in GitHub)

This article is intended to a Distribution Package user (see Which Package better suits your needs for more information).

1. Prerequisites

The environment must be installed using the Distribution Package adapted to your selected microprocessor device, STM32MP1 Distribution Package for Android.

The kernel sources must have been downloaded following How to build kernel for Android.

The following packages need to be installed to generate adeb:

 sudo apt-get install debootstrap qemu-user-static schroot

The following instructions should be launched from the distribution root directory STM32MP1 Distribution Package for Android, initialise your environment and then lunch:

 source build/envsetup.sh
 lunch aosp-<BoardId>-userdebug

You must have the right to execute commands as administrator on your machine.

Warning

You need to use a 8Gb SD card in order to be able to use adeb

2. Kernel preparation

On first step you need to get the kernel source and compile it, like explain in more details How to build kernel for Android.

 load_kernel
 build_kernel -i

The compilation output will be in out-bsp/<SocId>/KERNEL_OBJ

2.1. Kernel customisation for BCC

It's first required to add a tracepoint at the point where an SELinux denial is logged in the kernel.

For that purpose, you have to apply the patch 0999-add-SELinux-denial-tracepoint.patch on the kernel source.

 cd device/stm/<SocId>-kernel/linux-<SocId>
 git am ../source/patch/4.19/0999-add-SELinux-denial-tracepoint.patch

Then rebuild the kernel and regenerate the boot image

 build_kernel -i
 make -j

Then flash the boot partition (see Flashing the built image).

3. Adeb initialisation

If not already available , you have to retrieve the adeb repository, and put it in the external folder from the distribution.

 cd external

Clone the git.

 git clone https://android.googlesource.com/platform/external/adeb
 cd adeb

Have look at the adeb README.md in case of trouble

Create a sym link to the adeb executable to make things easier

 sudo ln -s $(pwd)/adeb /usr/bin/adeb

4. Adeb install

Warning

You need to have a device power on with Android connected to the computer and accessible via ADB

 adeb prepare --build --arch armhf --kernelsrc out-bsp/<SocId>/KERNEL_OBJ/

Information

A sudo password may be requested

A chroot debian environment will be pushed on the board.

Once adeb installed, we can use it by running the following command:

 adeb shell

5. Install BCC tools

To install the BCC tools, some dependencies need to be install in the debian. Make sure your board has access to the internet to be able to retrieve packages:

 Adeb $> apt update
 Adeb $> apt install git cmake clang-6.0 libclang-6.0-dev libelf-dev bison flex build-essential

Once all dependencies are installed, we can clone the BCC repository with the following command:

 Adeb $> git clone https://github.com/iovisor/bcc

5.1. Adapt BCC

By default, BCC is only working for 64-bit architecture and doesn't support 32-bit ARM device.

 Adeb $> cd bcc
 Adeb $> git checkout 1a47a9a
 Adeb $> exit

Push the file 0001-arm-make-bcc-32-bits-compatible.patch

 adeb push device/stm/<SocId>/patch/adeb/0001-arm-make-bcc-32-bits-compatible.patch
 adeb shell

 Adeb $> cd bcc
 Adeb $> git apply ../0001-arm-make-bcc-32-bits-compatible.patch

5.2. Compile BCC

It is recommended to create a swap to be able to compile BCC:

 Adeb $> dd if=/dev/zero of=/data/swapfile bs=1M count=400
 Adeb $> mkswap /data/swapfile
 Adeb $> swapon /data/swapfile

Now, we can install the BCC's trace tool using CMake with the following command in the bcc repo root directory

 Adeb $> mkdir build && cd build && CXX=/usr/bin/clang++-6.0 cmake .. -DCMAKE_INSTALL_PREFIX=/usr
 Adeb $> make && make install

The BCC tools uses some kernel headers that need to be provided in the androdeb environment.

To do so, push the kernel headers from the kernel source to the kernel-headers folder of the debian environment.

 adeb push out-bsp/<SocId>/KERNEL_OBJ/usr/include/* /data/androdeb/debian/kernel-headers/include/
 adeb push device/stm/<SocId>-kernel/linux-<SocId>/include/* /data/androdeb/debian/kernel-headers/include/

6. BCC's trace tool

6.1. Install

The BCC's trace tool auto-generates the code that will be compiled into eBPF.

This generated code uses kernel headers that are now incompatible with our patched BCC so we need to update the trace tool to use rewritten headers with our own types.

In the BCC repository, apply this patch '0001-trace-update-headers-to-make-trace-work-with-BCC-32-.patch' to fix the BCC's trace tool by running the following command:

Warning

Fichier à télécharger !!!!!

 Adeb $> cd bcc
 Adeb $>  git apply 0001-trace-update-headers-to-make-trace-work-with-BCC-32-.patch

This patch simply replace the kernel header used in the generated eBPF code by our own rewritten headers with the define and struct needed by the generated code.

Then reinstall the trace tool by launching the following commands:

 Adeb $> cd build
 Adeb $> make && make install

6.2. Usage

To launch the BCC's trace tool, simply run the following command:

 Adeb $>  trace -K -U 't:selinux:selinux_denied'

The BCC's trace tool should now print the user and kernel callstack every time a SELinux denied is raised.

7. Backup adeb

It is possible to backup the adeb folder in order to deploy it faster next times.

7.1. Saving

First you need to mount the userdata partition into your computer. Create the androdeb archive wherever you want:

 tar -cpf androdeb.tar.bz2 <mount point>/data/androdeb

7.2. Setup

Extract the previously created archive to the <mount point>/data/androdeb folder:

 tar -xphf androdeb.tar.bz2

8. Limitation

All the BCC tools that use kernel headers won't work without some modifications due to pointer size that need to be redefine. You need to apply the same kind of modifications like explain in #BCC's trace tool.

BPF compiler collection

eval,disco (Generic term used, to complete configuration modules paths depending on used board)

SD memory card (https://www.sdcard.org)

Android debug bridge (Android specific)