Logo Computer scientist,
engineer, and educator
• Articles • Software • The KBOX project
Please note that this page is obsolete. An all-new version of KBOX is now available — see the KBOX2 project pages

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

[Now with camels! A package is available that provides a Perl interpreter for the KBOX environment. See the Optional packages section for details.]

KBOX logo

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.

[Update, March 2013: I've had a few reports of KBOX not working on Android 4.2 devices, although it seems to be fine on 4.1. Because it fails with no diagnostic output, and I don't have a 4.2 device to test on, I am unable to investigate this problem. In addition, a number of people have expressed an interest in running KBOX with a different terminal emulator. Because many people don't want to read all the technical background and set everything up from scratch (although that would be the best way) I have documented a manual procedure that will work with other terminal emulators, and should work with Android versions after 4.2 as well. The details are here.]

Limitations — please read this

1. KBOX works on at least some Android 4.x, 3.x and 2.3 devices. It will not work on releases earlier than 2.3. DNS name resolution does not seem to work under 2.x, although it does under 3.x. I don't know why, and have no clear way to find out. DNS resolution is fine (for me) under 4.0. I have had reports of KBOX not working on 4.0 platforms, but it isn't clear why, or whether it would have worked on the same hardware with Android 3.x.

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

KBOX is a miniature, single-user Linux distribution, integrated into a terminal emulator for Android. It's single-user because there is no notion of user credentials, and all files belong to the same user. The actual user ID is assigned by the Android package installer, and is arbitrary.

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

Download

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

I've tried to include as many of the busybox utilities as I could get to build under the Android NDK. Some only work in part (e.g., you can get the date, but not set it) because of Android limitations and security restrictions. But the basic stuff — find, grep, tar, vi — is all there.

ssh (client)

Provided by dropbear. Keys will be cached in $HOME/.ssh in the usual way. No non-standard arguments need be used, but bear in mind that you'll have to specify a specific user for the remote service because the Android user ID is arbitrary in a non-rooted device.

scp

In this system, scp is actually a shell script that runs the proper scp with arguments appropriate to the unconventional file layout KBOX uses.

ssh (server)

This is a somewhat modified version of the dropbear ssh server. On an incoming connection it launches kbox_shell instead of the Android shell, so that the user is provided with a workable environment.

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

At present there are only a few optional packages. If there is interest, I might be able to provide other Linux utilities as add-on packages.

How to install optional packages

Packages are installed using the dpkg utility (supplied as part of busybox). Please note that you can install (dpkg -i) and list (dpkg -l) packages but not remove or update them. This is a known limitation of busybox, and one that doesn't have a fix at present.

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
It should not need to be said, but just in case: although there add-ons are in Debian package format, an attempt to install any other Debian package will most likely fail catastrophically.

andplay

Download

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

$ andplay [files...]
andplay has the slight advantage over utilities like mpg123 that all it does is invoke the built-in media server in Android. Memory and CPU usage are therefore very low.

bc

Download

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

Download

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

Download

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

Download

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

Download

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

Download

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

Download

KCalc

Download

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

KCrypt

Download

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

Download

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

Download

rsync as a client

rsync can be used as a client with the default use of ssh to start the server on the remote system. It can also be used to talk to a stand-alone rsync daemon. I haven't (yet) included an rsh client, so the use of rsh to start a remote session (-e rsh) isn't working.

rsync as a server

At present, rsync can only be run as a server in stand-alone daemon mode. This mode does not require any other dameon processes (e.g., sshd) to be running on the device. The potential downside is that there is no authentication of clients, so such a daemon should probably not be left running for extended periods. The command line to start the rsync daemon is:
% rsync --daemon --config [config_file] --port [port] --no-detach \
  --log-file /dev/null 
You don't need to redirect the log to /dev/null — but the standard log location won't work, so you'll have to send it somewhere. The config file specifies what files will be made available in what modes, and how they will be identified by the client. A sample config file is provided in $KBOX/etc/rsyncd.conf. This config makes all files available, read/write, under the identifier 'all'. The client will do transfers like this:
% rsync --port [rsync_port] [device_ip]::all/path/to/file [local_path]
This is essentially the normal usage of rsync as a client, except that the path is prefixed ':all', and the port number is given explicitly.

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

Download

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

Download

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

KBOX works by providing the base distribution of utilities packed into an archive, such that the archive is installed along with the Java terminal app. The terminal app runs a script which either exec's bash in the usual way, or unpacks the whole distribution if this is the first session. The compressed archive remains in place — it can't be deleted as it's considered to be part of the app's code — but is largely useless after first run. However, it does make it possible to reset the base distribution to defaults if it gets completely broken — there is a script reinstall_kbox.sh that will do this.

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.

Shared objects are stored in $KBOX/usr/lib, and the LD_LIBRARY_PATH variable references this locatin. However, the Android dynamic linker is a bit peculiar, and some applications do not seem to be able to load dynamically, while others can, for no obvious difference.

Legal, etc.

Everything in KBOX is open source — usually, but not invariably, distributed according to the terms of the GNU Public Licence. It is the work of many authors, over many years. Source code for my modest contribution is available on request. Sources for busybox, dropbear, etc., are widely available on the Web. Getting these things to build for Android was frequently difficult. If you're struggling with the same thing, please get in touch, and maybe I can save you some head-beating.

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

22/04/13 Added epub2txt
18/04/13 Added frobtads
17/04/13 Added glulxe and kcalc
12/03/13 Added Perl package
09/03/13 Added kcrypt
26/10/12 Incorporated version 1.0.48 (latest available) of Jack Palevich's terminal emulator app.
25/10/12 Added frotz package
24/10/12 Updated base package, to fix missing scp.bin

Copyright © 1994-2013 Kevin Boone. Updated May 01 2013