pox

Documentation

Overview

pox builds a portable executable as a squashfs image. It is intended to create files compatible with tinycore tcz files. One of more of the files can be programs but that is not required. This could have been a simple program but mksquashfs does not preserve path information. Yeah.

Synopsis:

pox [-[-debug]|d] [-[-file]|f tcz-file] -[-create]|c FILE [...FILE]
pox [-[-debug]|d] [-[-file]|f tcz-file] -[-run|r] PROGRAM -- [...ARGS]
pox [-[-debug]|d] [-[-file]|f tcz-file] -[-create]|c -[-run|r] PROGRAM -- [...ARGS]

Description:

pox makes portable executables in squashfs format compatible with
tcz format. We don't build in the execution code, rather, we set it
up so we can use the command itself. You can either create the TCZ image
or run a command within an image that was previously created.

Options:

debug|d: verbose
file|f file: file name (default /tmp/pox.tcz)
run|r: Runs the first non-flag argument to pox.  Remaining arguments will
       be passed to the program.  Use '--' before any flag-like arguments
       to prevent pox from interpretting the flags.
create|c: create the TCZ file.
zip|z: Use zip and unzip instead of a loopback mounted squashfs.  Be sure
       to use -z for both creation and running, or not at all.
For convenience and testing, you can create and run a pox in one command.

Example:

	$ pox -c /bin/bash /bin/cat /bin/ls /etc/hosts
	Will build a squashfs, which will be /tmp/pox.tcz

	$ sudo pox -r /bin/bash
	Will drop you into the /tmp/pox.tcz running bash
	You can use ls and cat on /etc/hosts.

	Simpler example, with arguments:
	$ sudo pox -r /bin/ls -- -la
	will run `ls -la` and exit.

	$ sudo pox -r -- /bin/ls -la
	Syntactically easier: the program name can come after '--'

	$ sudo pox -c -r /bin/bash
     Create a pox with a bash and run it.

Notes: - When running a pox, you likely need sudo to chroot

- Binaries run out of a chroot often need files you are unaware of. For instance, if bash can't find terminfo files, it won't know to handle backspaces properly. (They occur, but are not shown). To fix this, pass pox all of the files you need. For bash: `find /lib/terminfo -type f`.

Other programs rely on help functions, such as '/bin/man'. If your program has built-in help commands that trigger man pages, e.g. "git help foo", you'll want to include /bin/man too. But you'll also need everything that man uses, such as /etc/manpath.config. My advice: skip it.

- When adding all files in a directory, the easiest thing to do is: `find $DIR -type f` (Note the ticks: this is a bash command execution).

- When creating a pox with an executable with shared libraries that are not installed on your system, such as for a project installed in your home directory, run pox from the installation prefix directory, such that the lib/ and bin/ are in pox's working directory. Pox will strip its working directory from the paths of the files it builds. Having bin/ in the root of the pox file helps with PATH lookups, and not having the full path from your machine in the pox file makes it easier to extract a pox file to /usr/local/.

- Consider adding a --extract | -x option to install to the host. One issue would be how to handle collisions, e.g. libc. Your app may not like the libc on the system you run on.

• pox is not a security boundary. chroot is well known to have holes. Pox is about enabling execution. Don't expect it to "wall things off". In fact, we mount /dev, /proc, and /sys; and you can add more things. Commands run under pox are just as dangerous as anything else.