This page explains how to run the Celadon Android* image in a Docker* container.
Description
CiC is Intel’s open source Android solution for running Celadon on a Linux based container environment, in order to achieve high-scalability, low performance overhead for some emerging use cases such as Cloud Gaming, IOT and FCF.
To support CiC running multiple Android instances on a single kernel without interfering each other, the following isolation approach is implemented:
I/O Devices
Kernel
Shared resources consumed by the Android instances should be isolated.
- CPU, Memory are isolated using CGroup.
- Binder is isolated by adding multiple device nodes.
Usespace
Running CiC requires modern PCs with 6th generation or newer Intel® Architecture Processors with integrated GPU. The Intel NUC model NUC7i7BNH and model NUC7i5BNH are recommended devices to try out the CiC features.
Note
The current version of CiC is 0.5, which provides a preview of the feature for pilot and development purposes. Some features such as Trusty, Verified Boot, and the OTA update do not exist in this preview version. We plan for these features in upcoming releases.
Prerequisites
Set up Security-Enhanced Linux (SELinux)
-
On the target device, CiC currently requires Ubuntu 18.04.3 or later running SELinux module enabled Linux* kernel, Ubuntu 20.04 (Focal Fossa) is recommended. Though SELinux module may be enabled in the Ubuntu kernels by default, you have to hook the module to the kernel through the Linux Security Module (LSM) framework. The following command adds the required kernel command line option to the configuration file template
/etc/default/grub
of GRUB bootloader, in order to hook the SELinux module to the kernel LSM framework.$ sudo vi /etc/default/grub
Modify the GRUB_CMDLINE_LINUX setting as follows:
... GRUB_CMDLINE_LINUX="lsm=yama,loadpin,integrity,selinux" ...
-
Update the bootloader with the new setting and reboot the device with the following commands:
$ sudo update-grub Sourcing file `/etc/default/grub' Generating grub configuration file ... ... Adding boot menu entry for EFI firmware configuration Done $ sudo reboot
Set up Docker Engine
-
You must install Docker on both the development host and the target device. Enter the following commands to install the prerequisites, set up the repository, and install the Docker Engine. Refer to the Get Docker Engine - Community for Ubuntu installation guide for more detailed information.
$ sudo apt-get install apt-transport-https ca-certificates curl $ curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo apt-key add - $ sudo add-apt-repository "deb [arch=amd64] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" $ sudo apt-get update $ sudo apt-get install -y docker-ce docker-ce-cli containerd.io $ sudo usermod -aG docker $USER
Note
The last command is optional if you want to run the Docker as a non-root user.
-
Restart your session for changes to take effect.
Build the CiC Package
-
Refer to the Build Celadon From Source section in the Getting Started Guide to set up the Celadon source tree and the build environment. There are two build targets associated with the CiC builds:
cic
The lunch target which is Android CDD compliant.
cic_dev
The lunch target for development purposes (available on the CiC branch of the Celadon Android-P release). This lunch target is deprecated.
-
Run the following commands to select cic-userdebug as the lunch target and start the build. The CiC package is generated at
$OUT/$TARGET_PRODUCT-*.tar.gz
.$ source build/envsetup.sh $ lunch cic-userdebug $ make cic -j $(nproc)
Deploy on Target
-
Download and extract the CiC package tar file on the target device.
-
The CiC image supports secure mode and non-secure mode. In secure mode, Trusty is enabled and SELinux policy is set to enforcing mode, thus you can’t modify the /system partition, update the docker container is not possible. In addition, since Trusty should implement a secure storage service based on the RPMB partition in eMMC, the following step includes instructions on how to set up a teedata partition to simulate the RPMB secure storage.
In contrast, Trusty is disabled and SELinux policy is set to permissive mode in non-secure mode. The container can be updated, and you can modify the /system partition as well.
-
Skip this step if you are setting up the CiC image in non-secure mode.
-
A ‘teedata’ disk partition is required to run CiC in secure mode. Create a new disk partition of 32M bytes in size with the name ‘teedata’ if there are unallocated disk space on the target device. You may reference this article to shrink the root partition of an existing Ubuntu setup, if no disk space can be reserved as the teedata partition.
The following example boots the device from a Ubuntu live-CD, runs the gparted utility, right-clicks the root partition and selects Resize/Move item to reserve 32MB disk space at the bottom of the root disk:
-
To create a ‘teedata’ partition, right-click the unallocated partition, select New item, create a new partition named “’teedata”, set its label to “’teedata” as well, and leave the File system “unformatted”:
-
The first disk partition used to be the EFI System Partition, please rename it to “EFI” by right-clicking the partition, and select Name Partition item:
-
Finally, click Edit then Apply All Operations items for changes to take effect.
-
Before rebooting the Ubuntu system, make sure the Secure Boot feature is disabled in the UEFI firmware:
-
-
Run the
setup-aic
script to install the container images. You can pass ‘-s’ argument to the script to set up the containers in secure mode, or ‘-ns’ argument for non-secure mode.Note
To run CiC in secure mode, make sure you have ever set up a teedata partition for the RPMB simulation. Check out the previous step for detailed information.
# The following command sets up CiC in non-secure mode $ sudo -E ./setup-aic -ns
# The following command sets up CiC in secure mode $ sudo -E ./setup-aic -s
Note
-
If you are setting up the CiC in secure mode, some of the Ubuntu startup files in the ESP are overwritten by the
setup-aic
script. Specifically, the bootloader shim fileshimx64.efi
is replaced bykf4cic.efi
in the CiC package. The original shim file is renamed asloaderx64.efi
. In addition, thetos.img
image, which contains the Trusty OS, is copied to the ESP partition as well. -
Since the Ubuntu booting sequence has been extended to run the Trusty OS, you would see the following warning during the system startup as the secure boot is disabled:
-
-
Reboot the device after the installation.
-
The
setup-aic
script not only set up CiC docker images on the target device, but also installed a systemd service ‘cic’ to launch the CiC container images automatically on system startup. You can verify whether the CiC containers are running successfully with the following command:$ sudo docker ps CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES b5186e3c2116 android:CC0000105-cic-userdebug "/android-entry -e 0" 5 minutes ago Up 2 minutes 0.0.0.0:5555->5555/tcp android0 f077a4eb722c aic-manager:CC0000105-cic-userdebug "/aic-manager-entry ..." 5 minutes ago Up 2 minutes aic-manager
-
In addition, an Android Container Client for Linux script ‘cfc’ and its desktop file cfc.desktop are also installed on the Gnome desktop. Run the cfc script in a shell terminal or launch the cfc.desktop from the GUI, a full screen window pops up and shows the Android home screen:
Note
CiC runs as a Docker container, as a result, you can use Docker CLI commands directly for debugging. For example, if you encounter issues, you can capture necessary information by running the following commands:
$ docker logs aic-manager 2>&1 | tee aic-manager.log $ docker exec -it android0 sh | tee android.log # run commands to get information, such as getprop logcat -b all