MINCS - Mini Container Shellscript
Shell
Clone or download
mhiramat ermine-breeder: Remove old modules from rootfs
Remove old modules from rootfs always.
Latest commit f8638b0 Jul 28, 2018
Permalink
Failed to load latest commit information.
libexec
samples
sigpack
test.d
.gitignore
LICENSE
README.md
ermine-breeder
install.sh
marten
minc
polecat
runtests.sh runtest: Add verbose console option Sep 24, 2017

README.md

MINCS

MINCS (Minimum Container Shellscripts) is a collection of shell scripts for light-weight containers. Since MINCS just requires posix shell and some tools, it is easy to run it even on busybox ( see Ermine for busybox combination).

  • minc is a shell script (frontend) of mini-container script, which works as the chroot, but it also changes namespace.

  • polecat is a shell script to build a self-executable containered application.

  • marten is a shell script to manage uuid-based containers and images.

  • ermine is a micro linux bootimage for qemu. MINCS has ermine-breeder to build ermine (vmlinuz and initramfs.)

Pre-requisites

  • Posix shell (dash, bash, etc)

  • coreutils

  • Util-linux ( version >= 2.24 for basic usage, and >= 2.28 for --nopriv )

  • IProute2 (for netns)

  • iptables (for netns)

  • bridge-utils (for netns)

  • Overlayfs

  • Squashfs-tools (for polecat)

  • libcap (for --nocaps option)

  • jq (for marten)

  • docker or debootstrap (for marten)

  • qemu-user-static (for --cross)

  • qemu-system (for --qemu)

  • Or, busybox ( version >= 1.25 ) and libcap (for minc/ermine)

Install MINCS

You can run commands in MINCS without installing, but you can also choose installing MINCS on your system. To install MINCS, just run install.sh as below;

 $ cd mincs
 $ sudo ./install.sh

By default, it installs MINCS under /usr/local/. If you would like to install it under /usr or other directory, Please specify PREFIX as below;

 $ sudo PREFIX=/usr ./install.sh

To uninstall it, run install.sh with --uninstall option. Note that you need to specify PREFIX if you gave it when installing.

minc usage

minc [options] [command [arguments]]

Options

  • -h or --help
    Show help message

  • -k or --keep
    Keep the temporary directory

  • -t or --tempdir DIR
    Set DIR for temporary directory (imply -k)

  • -r or --rootdir DIR|UUID|NAME
    Set DIR for original root directory

  • -b or --bind HOSTPATH:PATH
    Bind HOSTPATH to PATH inside container. The PATH must be an absolute path.

  • -B or --background
    Run container in background. The output of stdout and stderr are stored under tempororary directory.

  • -X or --X11
    Export local X11 unix socket. If XAUTHORITY is defined, this exports it too. (no need to setup xhost)

  • -n or --net [MODE]
    Use network namespace (IP address is assigned). MODE can be specified as a option. Currently available MODE is raw[,IF] and dens. In raw mode, minc makes new namespace but do nothing. In dens mode, minc generate bridge and veth pair and masquerade the network.

  • -p or --port PORT1[:PORT2[:PROTO]]
    Map host PORT1 to container PORT2 of PROTO (tcp or udp)

  • -c or --cpu BITMASK
    Set runnable CPU bitmask

  • --name UTSNAME
    Set container's utsname

  • --user USERSPEC
    Run command as given uid:gid

  • --cross arch
    Run command with given arch (require setting up qemu-user-mode)

  • --arch arch
    Same as --cross.

  • --nopriv rootdir
    Run command in given rootfs without root privilege

  • --qemu
    Run command in Qemu (like Clear Container, see Ermine)

  • --nocaps CAPLIST
    Drop capabilities (e.g. cap_sys_admin)

  • --pivot
    Use pivot_root forcibly instead of chroot. This requires chroot and umount installed on container's rootfs.

marten usage

marten <command> [arguments...]

Command

  • lc or list
    List containers

  • li or images
    List images

  • rm UUID
    Remove specified container

  • import DIR|DOCKERIMAGE
    Import DIR or DOCKERIMAGE as an image

  • pull DOCKERTAG
    Import Docker image from dockerhub (without docker)

  • commit UUID
    Commit specified container to image

  • rename UUID NAME
    Rename given UUID container to NAME

  • renamei UUID NAME
    Rename given UUID image to NAME

  • tag UUID NAME
    An alias of renamei (for image)

Opitons

  • -h or --help
    Show help message

Mixed example of minc and marten

 $ sudo debootstrap stable debroot
 $ sudo marten import debroot
c45554627579e3f7aed7ae83a976ed37b5f5cc76be1b37088f4870f5b212ae35
 $ sudo minc -r c455 /bin/bash

Mixed example of minc and Docker :)

 $ sudo docker save centos | gzip - > centos.tar.gz
 $ sudo marten import centos.tar.gz
Importing image: centos
511136ea3c5a64f264b78b5433614aec563103b4d4702f3ba7d4d2698e22c158
5b12ef8fd57065237a6833039acc0e7f68e363c15d8abb5cacce7143a1f7de8a
8efe422e6104930bd0975c199faa15da985b6694513d2e873aa2da9ee402174c
 $ sudo marten images
ID              SIZE    NAME
511136ea3c5a    4.0K    (noname)
5b12ef8fd570    4.0K    (noname)
8efe422e6104    224M    centos
 $ sudo minc -r centos /bin/bash

Or, you can now download docker image from marten directly.

 $ sudo marten pull ubuntu
Trying to pull library/ubuntu:latest
Downloading manifest.json
Downloading config.json
######################################################################## 100.0%
Downloading sha256:c62795f78da9ad31d9669cb4feb4e8fba995a299a0b2bd0f05b10fdc05b1f35e
######################################################################## 100.0%
Downloading sha256:d4fceeeb758e5103c39daf44c73404bf476ef6fd6b7a9a11e2260fcc1797c806
######################################################################## 100.0%
Downloading sha256:5c9125a401ae0cf5a5b4128633e7a4e84230d3eb4c541c661618a70e5d29aeff
######################################################################## 100.0%
Downloading sha256:0062f774e9942f61d13928855ab8111adc27def6f41bd6f7902c329ec836882b
######################################################################## 100.0%
Downloading sha256:6b33fd031facf4d7dd97afeea8a93260c2f15c3e795eeccd8969198a3d52678d
######################################################################## 100.0%
Pulled. Importing image: library/ubuntu
c62795f78da9ad31d9669cb4feb4e8fba995a299a0b2bd0f05b10fdc05b1f35e
d4fceeeb758e5103c39daf44c73404bf476ef6fd6b7a9a11e2260fcc1797c806
5c9125a401ae0cf5a5b4128633e7a4e84230d3eb4c541c661618a70e5d29aeff
0062f774e9942f61d13928855ab8111adc27def6f41bd6f7902c329ec836882b
6b33fd031facf4d7dd97afeea8a93260c2f15c3e795eeccd8969198a3d52678d

polecat usage

polecat [options] <rootdir> <command>

Options

  • -h or --help
    Show help message

  • -o or --output FILE
    Output to FILE instead of polecat-out.sh

Examples

To build an executable debian stable container, run a debootstrap on a directory and run polecat.

 $ sudo debootstrap stable debroot
 $ sudo polecat debroot /bin/bash

You'll see the polecat-out.sh in current directory, that is a self-executable binary. So, you can just run it.

./polecat-out.sh

Ermine

Ermine is not a shell script, but it is a micro linux boot image which is used for qemu container (minc --qemu). MINCS has a build script for ermine called "ermine-breeder". You can build your own ermine on your machine.

ermine-breeder usage

ermine-breeder [command] [option(s)]

Commands

  • build
    Build ermine by using host toolchain (default)

  • clean
    Cleanup workdir

  • selfbuild [DIR] [OPT]
    Setup new rootfs and build (will need sudo) If DIR is given for rootfs, use the directory as new rootfs.

  • testrun [--arch ] [DIR]
    Run qemu with ermine image

Options

  • --repack
    Rebuild ermine image without cleanup workdir (only the kernel will be rebuilt)

  • --rebuild
    Rebuild ermine image with cleanup workdir

  • --config CONF_FILE
    Use CONF_FILE as config

  • --arch ARCH
    Build ermine for ARCH (x86_64, arm, arm64)

Example

To build the ermine by ermine-breeder, you can choose either one of below.

  • Install build tools for kernel and busybox (also static-linked glibc) on your environment by using apt/yum/dnf etc.
  • Install debootstrap and setup sudo (since debootstrap requires root privilege)

If you choose the former, you'll just need to run ermine-breeder. For latter, run ermine-breeder selfbuild to build it.

Under samples/ermine/, there are some example configs. E.g.

 $ ./ermine-breeder --config samples/ermine/smallconfig

This will build ermine with small-size configuration, result in less than 5MB.

Multi config files are also supported, so that you can combine different configs by giving multi --config CONF options. Note that settings in configs are overwritten by latter config.

Building Cross-arch Rootfs

When you run minc with --arch/--cross option, you'll need a rootfs directory for the target architecture. One recommended way to get it is using cross-debootstrap which allow you to build debian-based cross-arch rootfs. To setup it easily, there is a sample script. For example, if you would like to build a rootfs for arm, run below command.

$ sudo ./samples/scripts/build-debian-rootfs.sh ./rootfs/arm arm

This build debian jessie (debian 8) rootfs arm port under ./rootfs/arm directory. So after it finished, you can run minc as below;

$ sudo minc -r ./rootfs/arm --arch arm

Known issues on major distros

  • On Fedora 24/x86_64, qemu-static's aarch64 setup has an issue. You must setup a binfmt config file for qemu-aarch64 to run with --cross aarch64.

  • On Ubuntu 16.04/x86_64, qemu-system's aarch64 will not work without installing qemu's UEFI image. (It seems that qemu-efi package doesn't help, you need to install it from pcbios directory in qemu's source code to /usr/share/qemu/)

  • If you can't make it work, you can also build your own qemu-system-arm/aarch64 from source as below:

$ cd qemu
$ ./configure --target-list=arm-softmmu,aarch64-softmmu --enable-virtfs
$ make

License

This program is released under the MIT License, see LICENSE.