KBOX — a miniature Linux distribution integrated with a terminal for non-rooted Android devices

KBOX is a project to create a miniature Linux distribution for non-rooted (i.e., unmodified) Android devices, integrated directly into Jack Palevich's Android terminal emulator (see here). Installing the Android package (see below) gives you the terminal emulator, a decent set of Linux utilities (supplied by busybox), ssh and rsync clients and servers, and a few other things. In addition, there are a number of add-on packages for expanded functionality.

I do want to stress that the credit for developing the terminal emulator and making it open source belongs to Mr Palevich — I have not changed it beyond the minimum needed to integrate my utilities. You can use my package side-by-side with the original terminal emulator on the same device: they should not clash. Uninstalling the package will remove the whole thing including add-on packages, except for data created by the user on the SD card.

The technical background to the KBOX project is explained here and here. Android is not Linux, and there's a limit to how far one can emulate a desktop Linux on a non-rooted Android devices. I would certainly recommend reading the more technical documents to get an idea of why KBOX operates the way it does.

Please note that 'download' links are hidden in the document, to encourage people to read at least some of this stuff before leaping into installing the software.

Limitations — please read this

2. KBOX won't ever be appearing on the Android market. To install it you'll need to download the packages and optional components and install from the Android browser or a file manager. This is disallowed by default — you'll need to enable the setting 'Allow installation of non-market applications' in the Android settings applet.

3. There is no X server for Android (yet). It's likely that many X applications can be built to run on Android but, without an X server, it's not clear that there's much point. A port of Xvnc is available, so it's possible in principle to run X applications using that and a VNC viewer. While academically interesting, this doesn't seem very practical to me. My point is that there's little point asking me if I can port Firefox or OpenOffice — it's terminal utilities only at the moment. [Update, January 2013: it's been brought to my attention that there is some work in progress to produce a native X server for Android. I'm not sure how stable this project is yet.]

4. Fiddling with Linux is a hobby, not an occupation. If it doesn't work for you, I'll very likely not have time to fix it. Full source code is available, if you want to fix it yourself :)

Overview

Because an unpriveleged user has very limited access to the filesystem, the entire root filesystem is located somewhere under the Android app's preferences directory. From a Linux perspective this makes no sense, but is necessary. Most Linux utilities — even simple ones — expect a conventional file layout, with directories '/etc', '/usr', etc. This is impossible in this application, and most of the Linux utilities that have been ported to KBOX have required some reworking to account for the unconventional file layout. For the most part, however, the file layout is not particularly visible to the user.

By default, the user's home directory is /sdcard/kbox_home/[user_id] , where 'user_id' is the arbitrary ID created by Android. The KBOX user has full read-write access to the SD card area.

It's important not to expect any file to be in the place it would be on a conventional Linux system — all the conventional locations are write-protected on a non-rooted device. The environment variable $KBOX points to the root of the KBOX installation, below which you'll find the usual Linux directories.

Basic distribution

Last update: October 25, 2012

The basic distribution contains Jack Palevich's terminal emulator, busybox, and the the ssh server and client from the dropbox project.

busybox

ssh (client)

scp

ssh (server)

kbox provides a script ssh_daemon.sh that will launch the ssh server with the appropriate arguments, specifying user credentials and port number on the command line. The port number comes from $KBOX/etc/kbox_ports.sh. As always, the port number must be above 1024 for non-root usage. In addition, the user ID (specified by the -U argument) must be the user ID of the terminal emulator app running the script. ssh_daemon.sh takes care of these issues, and can be used as a template for more appropriate customization. Note that this script sets the current username as the password, which isn't hugely secure.

The script will read an RSA server key from $HOME/.rsa_host_key. The dropbearkey utility can be used to create this key, but it should be created automatically when a user logs in on console for the first time.

In order to connect to the sshd server run as described above, clients need to specify the port number on the command line (e.g., ssh -p 10022 [my_andoid_ip]).

Optional packages

How to install optional packages

The simplest way to install is probably to download using the Android browser, which will put the files in /sdcard/Downloads. Then in the console:

$ dpkg -i /sdcard/Download/[file].deb

andplay

A simple utility I wrote to play music files at the command line. Usage:

$ andplay [files...]

bc

The scientific calculator application. I have included the general function library from phodd.net, and the bc script will load this automatically. The built in functions don't work anyway, for some reason. So if you want sine function, do sin() rather than the older s() etc. But look at phodd.net for full details.

epub2txt

A simply utility for extracting and formatting text from EPUB e-books. epup2txt my_book.epub|more makes a servicable reader for EPUB e-books althrough there are, of course, fully featured graphical EPUB readers for Android. For more information, see here.

frobtads

frobtads is an interpreter for TADS games like 'Ecdysis.' If you don't know what that means, you probably won't be interested in this. For more information, see here.

frotz

frotz is an interpreter for z-code games like 'Zork' and 'Sherlock'. If you don't know what that means, you probably won't be interested in this. This version supports text styles and colouring, but not sound (it requires old-style OSS audio drivers, which Android does not provide). If you install an Android keyboard with cursor keys, it supports line editing and history, too. Unfortunately, as with any terminal-based application, fonts are fixed pitch, and this can be irritating when reading large amounts of text. From this point of view, 'ZMPP' is a better z-code interpreter, but Frotz under KBOX is faster, because it is written entirely in C and runs natively on the Android OS, and supports line editing, ASCII art, menus, and many other features that the Android apps lack. For more information, see here.

gawk

The GNU version of the awk text processing language. I'm not really an awk user myself, so there's not a lot I can do to check this works fully. Please note that I haven't included the source-code library files (*.awk) in this package. Presumably they could be copied from desktop Linux installation if required.

glulxe

glulxe is a console-based runtime environment for for the Glulx interactive fiction system. It supports line editing and simple text formatting. For more information about interactive fiction under KBOX, see here.

hexedit

KCalc

KCalc is a lightweight, command-line calculator, intended to fill the gap beween bc and Matlab. For more information, see here.

KCrypt

KCrypt is a simple, command-line file encrypter and obfuscator. It is designed to offer reasonable security, while still being convenient to use. For full details, see the main project page here.

Please bear in mind that KCrypt was originally a Windows program; it has had relatively little testing on Android. Please use with considerable caution.

Perl

Because cross-compiling Perl is a real pain, I have extracted a pre-compiled version from the Android Scripting Environment project, and re-packaged it as an add-on package for KBOX. The original executable is renamed perl.bin, and perl becomes a wrapper script for that binary, with the appropriate environment for use with KBOX.

This version of Perl is 5.10.0, and it is a fairly minimal build — a lot of the optional components are not included, particularly those that require supporting C libraries that might not even exist on Android. There is no support for big numbers (use bigint, etc) or threading. However, it seems basically functional for routine file and text manipulation.

rsync

rsync as a client

rsync as a server

% rsync --daemon --config [config_file] --port [port] --no-detach \
  --log-file /dev/null 

% rsync --port [rsync_port] [device_ip]::all/path/to/file [local_path]

Note that the rsync daemon will have access only to the same files as the terminal emulator has, in an unrooted device.

To simplify usage, there is a script rsync_daemon.sh that starts the daemon as above, with a port number taken from kbox_ports.sh.

solunar

solunar is a command-line utility for displaying sunrise, sunset, moon phase, and related data, for specific locations. For more information, see here. Please note that, when using times other than GMT/UTC, solunar is only as accurate as the platform's underlying ability to handle timezone conversions. This is something of an unknown with Android.

vim

The complete build of vim, including syntax highlight files, tutorial, etc. This is quite a large package by mobile device standards. Note that vim does not replace vi, so you'll need to run it as vim explicitly. You can put startup commands in $HOME/.vimrc in the usual way.

Technical notes

Add-on packages are provided in Debian package format, because busybox happens to include support for that format. Inside the package the file locations are as in conventional Linux — that is, rooted at '/'. The busybox packager manager has been extensively hacked to account for the unconventional file layout KBOX is forced to adopt.

When the terminal session starts, the environment variable $KBOX is set to point to the root of the KBOX filesystem. Nearly all the modified utilities make use of this variable to find files.

Legal, etc.

Known issues

• ifconfig segfaults when trying to obtain the settings of the wifi interface. The Android platform does not expose this information in a way that is useful to native applications, anyway
• Packages installed using dpkg cannot be removed, or overwritten with new versions. This is a limitation of the way I have modified the utility to work with KBOX, and can probably be fixed
• On some Android versions, sshd, telnetd will not accept incoming connections. This effectively prevents these utilities being used. The problem is that some Android versions simply block incoming connection packets using the software firewall. In some cases, a workaround is to make a connection (any kind of connection) from the Android device to the prospective client's IP number — this seems to fool the wirewall into opening. This isn't a very satisfactory workaround but, sadly, the problem lies in Android
• Early versions of Klaus Weidner's 'Hacker's Keyboard' do not work very well with later versions of KBOX. For example, some of the special keys do not generate any input. The solution is to upgrade the keyboard app

Revision history