================================================== Kains — container tool based on Linux namespaces ================================================== Synopsis ======== kains [options] ... [command] Description =========== Kains's main purpose is to confine programs within a virtual rootfs. However it is possible to selectively make files of the actual rootfs visible from the virtual rootfs. Kains can also be used to make files and directories accessible elsewhere in the file-system hierarchy. Kains does not need any privileges or setup, although it requires Perl 6 runtime and a Linux kernel that supports user namespaces. Options ======= The command-line interface is composed of two parts: first Kains's parameters, then the command to launch (the default is "/bin/sh -l" if none is specified). This section describes the parameters supported by Kains, that is, the first part of its command-line interface: -r $path --rootfs $path Use $path as the new root file-system, aka. virtual rootfs. Programs will be executed from, and confined within the virtual rootfs specified by $path. Although, files and directories of the actual rootfs can be made visible from the virtual rootfs by using "-b" and "-B". By default the virtual rootfs is "/", this makes sense when using "-B" to relocate files within the actual rootfs, or when using "-0" to fake root privileges. It is recommended to use "-R" or "-S" instead. Some examples: -r ~/rootfs/centos-6-x86 -r /tmp/ubuntu-12.04-x86_64 -r / (default) -b $path -m $path --bind $path --mount $path Make $path visible from the virtual rootfs, at the same location. The content of $path will be made visible from the virtual rootfs. Unlike with "-B", the location isn't changed, that is, it will be accessible as $path within the virtual rootfs too. Some examples: -b /proc -b /dev -b $HOME -B $path $location -M $path $location --bind-elsewhere $path $location --mount-elsewhere $path $location Make $path visible from the virtual rootfs, at the given $location. The content of $path will be made visible at the given $location from the virtual rootfs. This is especially useful when using "/" as the virtual rootfs to make the content of $path accessible somewhere else in the file-system hierarchy. Some examples: -B ~/my_hosts /etc/hosts -B /tmp/opt /opt -B /bin/bash /bin/sh -w $path --pwd $path --cwd $path --working-directory $path Set the initial working directory to $path. Some programs expect to be launched from a specific directory but they do not move to it by themselves. This option avoids the need for running a shell only to change the current working directory. Some examples: -w /tmp -w $PWD (first default) -w / (second default) -0 --root-id Set user and group identities virtually to "root/root". Some programs will refuse to work if they are not run with "root" privileges, even if there is no strong reasons for that. This is typically the case with package managers. This option changes the user and group identities to "root/root" in order to bypass this kind of limitation, however all operations are still performed with the original user and group identities. --32 --32bit --32bit-mode Make Linux declare itself and behave as a 32-bit kernel. Some programs launched within a 32-bit virtual rootfs might get confused if they detect they are run by a 64-bit kernel. This option makes Linux declare itself and behave as a 32-bit kernel. -R $path Use $path as virtual rootfs + bind some files/directories. Programs will be executed from, and confined within the virtual rootfs specified by $path. Although a set of files and directories of the actual rootfs will still be visible from the virtual rootfs. These files and directories contain information that are likely required by virtual programs: - /etc/host.conf - /etc/hosts - /etc/hosts.equiv - /etc/mtab - /etc/netgroup - /etc/networks - /etc/passwd - /etc/group - /etc/nsswitch.conf - /etc/resolv.conf - /etc/localtime - /dev/ - /sys/ - /proc/ - /tmp/ - /run/ - $HOME -S $path Use $path as virtual rootfs + bind some files/directories + fake "root". This option is similar to "-0 -R" but it makes visible from the virtual rootfs a smaller set of files and directories of the actual rootfs (to avoid unexpected changes): - /etc/host.conf - /etc/hosts - /etc/nsswitch.conf - /etc/resolv.conf - /dev/ - /sys/ - /proc/ - /tmp/ - /run/shm - $HOME This option is useful to create and install packages into the virtual rootfs. -h --help --usage Print the help message, then exit. -- @command Launch @command in the virtual environment. This option is only syntactic sugar since it is possible to specify the @command at the very end of the command-line, ie. after all other options. Some examples: -- emacs -- /usr/bin/wget -- /bin/sh -l (default) Exit Status =========== If an internal error occurs, Kains returns a non-zero exit status, otherwise it returns the exit status of the last terminated program. When an error occurs, the only way to know if it comes from the confined program or from Kains itself is to have a look at the error message. Tutorial ======== In this tutorial, it is assumed "~/rootfs/ubuntu-12.04/" contains files from an Ubuntu 12.04 system. See section "Download" to obtain such a rootfs easily. To confine a program using Kains, specify the path to the virtual rootfs using the "-r" option, followed by the program name and its arguments. For instance, the command below executes "cat /etc/motd" confined into "~/rootfs/ubuntu-12.04": $ kains -r ~/rootfs/ubuntu-12.04/ cat /etc/motd Welcome to Ubuntu 12.04.5 LTS Kains executes "/bin/sh -l" if no program is specified, thus the shortest way to confine an interactive shell is: $ kains -r ~/rootfs/ubuntu-12.04/ Once a program is confined, all its sub-programs are confined too. For example, when executing "cat /etc/motd" from the interactive shell above: $ cat /etc/motd Welcome to Ubuntu 12.04.5 LTS Although, some programs needs to access files of the actual rootfs. For instance: $ kains -r ~/rootfs/ubuntu-12.04/ $ ps -o tty,command Cannot find /proc/version - is /proc mounted? The solution is to tell Kains to make these files visible from the virtual rootfs, using the "-b" option: $ kains -r ~/rootfs/ubuntu-12.04/ -b /proc $ ps -o tty,command TT COMMAND ? [...] ? /bin/sh -l ? ps -o tty,command ? -bash Actually there's a bunch of such required files, that's why Kains provides an option that both confines and makes a predefined set of files visible from the virtual rootfs: $ kains -R ~/rootfs/ubuntu-12.04/ $ ps -o tty,command TT COMMAND pts/0 [...] pts/0 /bin/sh -l pts/0 ps -o tty,command pts/0 -bash It is possible that some programs will not work correctly if they are not run by the "root" user, this is typically the case with package managers. In this case, Kains will fake the root identity and its privileges if the "-0" (zero) option is specified: $ kains -r ~/rootfs/ubuntu-12.04/ -0 # id uid=0(root) gid=0(root) [...] # mkdir /tmp/foo # chmod a-rwx /tmp/foo # echo 'I bypass file-system permissions.' > /tmp/foo/bar # cat /tmp/foo/bar I bypass file-system permissions. This option is typically required to create or install packages into the virtual rootfs. However, it is not recommended to use the "-R" option when installing a package since it may try to update files of the host rootfs that were made visible from the virtual rootfs, like "/etc/group" for instance. Instead, it is highly recommended to use the "-S" option. This latter enables the "-0" option and make visible a smaller set of files that are known to not be updated by packages: $ kains -S ~/rootfs/ubuntu-12.04/ # apt-get install build-essential Reading package lists... Done Building dependency tree Reading state information... Done The following extra packages will be installed: [...] It is worth saying that the default path to virtual rootfs is "/" if none is specified. In this case, Kains is typically used to make files accessible somewhere else in the actual rootfs. This is useful to trick programs that perform access to hard-coded locations, like some installation scripts: $ kains -B /tmp/alternate_opt /opt $ cd to/sources $ make install [...] install -m 755 prog "/opt/bin" [...] # prog is installed in "/tmp/alternate_opt/bin" actually As shown in the example above, it is possible to override files or directories not even owned by the user. This can be used to change the system configuration temporally and locally, ie. without impacting programs not executed by Kains. For instance, with the DNS setting: $ ls -l /etc/hosts -rw-r--r-- 1 root root 675 Mar 4 2011 /etc/hosts $ touch ~/alternate_hosts $ kains -B ~/alternate_hosts /etc/hosts $ echo '1.2.3.4 google.com' > /etc/hosts $ resolveip google.com IP address of google.com is 1.2.3.4 $ echo '5.6.7.8 google.com' > /etc/hosts $ resolveip google.com IP address of google.com is 5.6.7.8 Another example: on most Linux distributions "/bin/sh" is a symbolic link to "/bin/bash", whereas it points to "/bin/dash" on Debian and Ubuntu. As a consequence a "#!/bin/sh" script tested with Bash might not work with Dash. In this case, Kains can be used to set non-disruptively "/bin/bash" as the default "/bin/sh": $ kains -B /bin/bash /bin/sh [...] Installation ============ Kains is written in Perl 6. The easiest way to get a Perl 6 runtime is to use rakudobrew: $ git clone https://github.com/tadzik/rakudobrew ~/.rakudobrew [...] $ export PATH=~/.rakudobrew/bin:$PATH $ rakudobrew build moar [...] $ rakudobrew build-panda [...] $ panda install ufo [...] Then, Kains can be installed that way: $ git clone https://github.com/cedric-vincent/kains $ cd kains $ ufo $ make install [...] $ export PATH=~/.rakudobrew/moar-nom/install/share/perl6/site/bin:$PATH Rootfs ====== Here follows a couple of URLs where some archived rootfs can be freely downloaded. Note that "mknod" errors reported by "tar" when extracting these archives should be ignored since special files of the actual rootfs can be made visible from the virtual rootfs (see "-R" option for details). - http://download.openvz.org/template/precreated/ - https://images.linuxcontainers.org/images/ - http://distfiles.gentoo.org/releases/ - http://cdimage.ubuntu.com/ubuntu-core/releases/ - http://archlinuxarm.org/developers/downloads Technically such archived rootfs can be created by running the following command on the expected Linux distribution: tar --one-file-system --create --gzip --file my_rootfs.tar.gz / License ======= The following copyright notice both applies to this file and to Kains sources: Copyright (C) 2015 STMicroelectronics This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.