InkBox GUI user apps

This page describes the internals of InkBox GUI's user applications feature.

Description

This GUI feature permits the user to run digitally signed external Qt/FB applications available at https://23.163.0.39/bundles/inkbox/apps.
User applications in are executed in their own chroot jail as an unpriviledged user, to prevent external access to parts of the filesystem and increase security. They are also mounted read-only, with some exceptions.

Application package

Contents

App packages have the .isa extension. Signature files (digests) have the .isa.dgst extension. A standard application package layout will look like this:

.
├── app-bin
│   └── SampleApp
│   └── SampleApp.bin
├── app-data
├── app.json
├── app-lib
│   └── libzip.so
├── app-misc
│   └── SampleApp.png
├── dev
├── etc
│   └── passwd
├── proc
├── sys
├── system-bin
└── system-lib

app.json

This file contains a description of the application in the JSON format that will be parsed by the GUI. A sample app.json may look like this:

{
  "app": {
    "Author": "John Doe",
    "AuthorContact": "johndoe@johndoe.com",
    "Enabled": true,
    "ExecPath": "/app-bin/SampleApp",
    "IconPath": "/app-misc/SampleApp.png",
    "Name": "SampleApp",
    "SupportedDevices": "all",
    "RequiredFeatures": [ 1 ],
    "Version": "0.1-testing"
  }
}

For more details on this file and its contents, please consult the related section below.

app-data

This directory contains the only read-write part of the extension package. It is actually a bind mount of the related path .apps-data/<app-name> in the exported USB mass storage. Applications can store their user data, such as preferences, files and statistics, there.
Applications can access this location at /app-data.

app-bin

This directory contains the application's binaries.
Applications can access this location at /app-bin

app-lib

This directory contains the libraries the application needs to have to function properly. If it is based on Qt, there is no need to bundle it in there, as it will be provided in the system-lib directory. In this example, the application requires libzip.so, so it has been put there. LD_LIBRARY_PATH environment variable is automatically adjusted by the main launch script.
Applications can access this location at /app-lib.

sys

This directory contains a mounted sysfs filesystem used by the chroot.

dev

This directory contains a mounted devtmpfs filesystem used by the chroot.

proc

This directory contains a mounted proc filesystem used by the chroot.

etc

This directory contains a mounted tmpfs filesystem used by the chroot.

system-lib

This directory contains the system's Qt libs and are made available so that the application can launch.
Applications can access this location at /system-lib.

system-bin

This directory contains the system's binaries made available to the application (e.g. BusyBox).
Applications can access this location at /system-bin.

Other files

Those may include an application icon that will be read by the GUI.

GUI launch process

The main Qt GUI will launch the application in the chroot jail as an unpriviledged user, based on its JSON file's ExecPath property. Once the program has finished running, the GUI will restart itself.

JSON app descriptor

The app.json file contains information about the application, how to run it and what system features it requires.

Properties

Author

Property containing the application author's name.

AuthorContact

Property containing the application author's contact e-mail address.

Enabled

TODO

ExecPath

Property containing the path to the main application's executable. The recommended location is at /app-bin/SampleApp.

IconPath

Property containing the path to the main application's icon.

Name

Property containing the name of the main application. It can be a full string with spaces.

SupportedDevices

Property containing an array of the application's supported devices. This can be, for example, [ "n236", "n437", "n306" ]. If the application aims to support every device, this property must contain the "all" string instead.

RequiredFeatures

Property containing an array of the application's required features. Features are functions of InkBox OS that are not always available based on user interaction (e.g. Wi-Fi connection). Below is a list of features that this property supports.

Feature identifier	Description
0	Wi-Fi connection required
1	Rooted kernel required

A simple array for this property may be, for example, [ 0, 1 ].

Backend setup

The service gui_apps in the main root filesystem manages the setup of user applications.