[](https://travis-ci.org/guillon/zoostrap/branches)
# Synopsis
The zoostrap utility is a simple tool for bootstrapping a Linux host
distribution and running command in an unprivileged container.
Actually this tool proceeds in three steps:
- download a reference distribution archive an extract into the specified
rootfs directory
- execute installation of additional packages into this rootfs with `PRoot`
- execute actual commands into this rootfs with `ckains`
The list of available x86_64 distributions is currently:
- Ubuntu 12.04 (`ZS_DISTRIB_ID=ubuntu ZS_DISTRIB_RELEASE=12.04`)
- Ubuntu 14.04 (`ZS_DISTRIB_ID=ubuntu ZS_DISTRIB_RELEASE=14.04`)
- Ubuntu 16.04 (`ZS_DISTRIB_ID=ubuntu ZS_DISTRIB_RELEASE=16.04`)
- Ubuntu 18.04 (`ZS_DISTRIB_ID=ubuntu ZS_DISTRIB_RELEASE=18.04`)
- Ubuntu 20.04 (`ZS_DISTRIB_ID=ubuntu ZS_DISTRIB_RELEASE=20.04`)
- CentOS 5 (`ZS_DISTRIB_ID=centos ZS_DISTRIB_RELEASE=5`)
- CentOS 6 (`ZS_DISTRIB_ID=centos ZS_DISTRIB_RELEASE=6`)
- CentOS 7 (`ZS_DISTRIB_ID=centos ZS_DISTRIB_RELEASE=7`)
- Fedora 20/21/22/23 (`ZS_DISTRIB_ID=fedora ZS_DISTRIB_RELEASE=20/21/22/23`)
Some x86 distributions are also available with the `ZS_DISTRIB_ARCH=i686`
parameter:
- Ubuntu 12.04 (`ZS_DISTRIB_ID=ubuntu ZS_DISTRIB_RELEASE=12.04 ZS_DISTRIB_ARCH=i686`)
- Ubuntu 14.04 (`ZS_DISTRIB_ID=ubuntu ZS_DISTRIB_RELEASE=14.04 ZS_DISTRIB_ARCH=i686`)
- CentOS 5 (`ZS_DISTRIB_ID=centos ZS_DISTRIB_RELEASE=5 ZS_DISTRIB_ARCH=i686`)
- CentOS 6 (`ZS_DISTRIB_ID=centos ZS_DISTRIB_RELEASE=6 ZS_DISTRIB_ARCH=i686`)
- Fedora 20 (`ZS_DISTRIB_ID=centos ZS_DISTRIB_RELEASE=20 ZS_DISTRIB_ARCH=i686`)
This tool is still a prototype and as of now configuration is passed through
the environment, refer to the TODO file for next steps.
Note that this tool requires a kernel >= 3.11.x in order to execute
unprivileged containers.
In particular if you have this kind of error:
`ERROR: unshare failed with error Invalid argument`. The host distribution
kernel is probably too old.
The tool uses 3 companions tools as backend:
- PRoot for installation of packages,
- ckains for execution of the container,
- bcache for cacheing of images.
See references section.
# Download
Download a specific release from the release page:
https://github.com/guillon/zoostrap/releases
Or download the last stable version from there:
https://raw.githubusercontent.com/guillon/zoostrap/master/zoostrap
For instance:
$ wget -O ~/bin/zoostrap https://raw.githubusercontent.com/guillon/zoostrap/master/zoostrap
$ chmod +x ~/bin/zoostrap
The first command gets the zoostrap tool and the second command sets execution bit.
# Examples
A typical usage is to bootstrap for instance a CentOS or Ubuntu distribution and then
execute a build command into the installed distribution root tree.
For instance, assuming zoostrap is available in the path:
$ env ZS_DISTRIB_ID=ubuntu ZS_DISTRIB_RELEASE=12.04 \
ZS_DISTRIB_PACKAGES="wget" \
zoostrap rootfs
$ rootfs/.zoostrap/run wget https://raw.githubusercontent.com/guillon/zoostrap/master/zoostrap
...
The first command installs a Ubuntu 12.04 core root tree in the rootfs/
directory and install the wget package.
The second command executes a wget command in the just installed distro.
One can also do this with a single command, passing the command to execute as parameter:
$ env ZS_DISTRIB_ID=ubuntu ZS_DISTRIB_RELEASE=12.04 \
ZS_DISTRIB_PACKAGES="wget" \
zoostrap rootfs wget https://raw.githubusercontent.com/guillon/zoostrap/master/zoostrap
...
# Parameters
zoostrap gets parameters from the environment except for the rootfs directory
to create which is passed as argument.
The available parameters are:
* `ZS_DISTRIB_ID="<distro>"`: one of the known distribution listed above.
* `ZS_DISTRIB_RELEASE="<release>"`: one of the known distro release listed above.
* `ZS_DISTRIB_ARCH="<uname-m>"`: the requested architecture for the
guest as may be provided by `uname -m` for instance. The default is the same
as the host architecture. It may be x86_64, amd64 (64 bits) or x86,
i[3456]86 (32 bits).
* `ZS_DISTRIB_PACKAGES="<packages list>"`: space separated list of packages to
install, note that package names are specific to distributions. It is up to
the user to give actual packages names as expected by the requested
distribution.
* `ZS_WGET="<wget command>"`: override default wget command and options.
The default wget command is: `wget --no-check-certificate --tries 3`.
Note that you may use `--no-check-certificate` without compromising
security as all downloaded files are checked against there known
content hash (a sha1sum).
* `ZS_BCACHE=false|true`: activates caching of installed images, defaults to
`false`. If `true` Images are cached after after download and packages
installation. The cached installed images are
used on further zoostrap installations if the image identifiers and installed
packages are the same. Cached images are stored into a local `ZS_BCACHE_DIR`.
The `ZS_BCACHE_ID` variable can be used to discriminate images optionally,
and have a guarantee that an image is stable (the actual base distro
archives may indeed vary over time), though this is not used generally.
Thus the actual identification of a unique cache entry is done at least with
the tuple (ZS_DISTRIB_ID, ZS_DISTRIB_RELEASE, ZS_DISTRIB_ARCH,
ZS_BCACHE_ID). This option uses the `bcache` tool.
* `ZS_BCACHE_DIR=<cache_dir>`: set location of cache when `ZS_BCACHE=true`,
defaults to `$HOME/.bcache`. Note that this location holds installed images
which may require some amout of disk space (generally 500Mb par installed
images with a reasonable number of user packegs). There is no management
of space provided by the tool, this location can be cleaned manually.
Note that the startup is much faster if this location is on the same
partition than the instelled root FSs.
* `ZS_BCACHE_ID=<any_stiing>`: optional discriminent for cached images. Ref to
`ZS_BCACHE` notes.
* `ZS_UPDATE=true|false`: run packages list update before installing packages,
defaults to ` true`. This should normally always be active as base distros
images do not have latest packages versions list.
* `ZS_UPGRADE=false|true`: run packages upgrade before installing packages,
defaults to `false`. This has an effect only for Ubuntu images and runs
an `apt-get upgrade` if `true`. This is normally not required, provided
just as an option. Note that if this is `true`, caching through `ZS_BCACHE`
is deactivated.
* `ZS_PACKAGES_STRICT/ZS_UPDATE_STRICT/ZS_UPGRADE_STRICT=true|false`: these
three variables control the error management on respectively packages
installation, packages update, packages upgrade. There are cases where
packages installation fail due to limitation of the non-privileged PRoot
backend. For instace some packages installation may try to restart damons or
create device nodes, which is not supported. If actually the installation is
correct even when such errors are reported, one may use
`ZS_PACKAGES_STRICT=false` to work-around the problem.
# Build and Install
This script requires bash and wget packages and should work on any Linux
distribution for x86_64 architecture with a kernel >= 3.0.
The script can be used directly without installation.
A makefile is provided for completion and testing purpose.
Build with:
$ make all # a no-op actually
Run unit tests with:
$ make check
Install with, for instance:
$ make install PREFIX=$HOME/local # Default is PREFIX=/usr/local
# References
Refer to the project home page at:
http://guillon.github.com/zoostrap
Refer to the current build and validation status at:
https://travis-ci.org/guillon/zoostrap?branches
Fill issues and enhancement request at:
https://github.com/guillon/zoostrap/issues
Refer to the TODO file for future work:
https://github.com/guillon/zoostrap/blob/master/TODO
Refer to ckains at: https://github.com/mickael-guene/ckains
Refer to PRoot at: http://proot.me
Refer to bcache at: https://guillon.github.com/bcache/
# License
Refer to the COPYING file: https://github.com/guillon/zoostrap/blob/master/COPYING
Refer to the COPYRIGHT file: https://github.com/guillon/zoostrap/blob/master/COPYRIGHT
](https://travis-ci.org/guillon/zoostrap/branches){kind=link}