Installation¶
Binary Installation¶
Note
If you’re ubuntu user you should use package. See instructions below.
Visit http://files.zerogw.com/vagga/latest.html to find out latest tarball version. Then run the following:
$ wget http://files.zerogw.com/vagga/vagga-0.6.0.tar.xz
$ tar -xJf vagga-0.6.0.tar.xz
$ cd vagga
$ sudo ./install.sh
Or you may try more obscure way:
$ curl http://files.zerogw.com/vagga/vagga-install.sh | sh
Note
Similarly we have a -testing variant of both ways:
$ curl http://files.zerogw.com/vagga/vagga-install-testing.sh | sh
Runtime Dependencies¶
Vagga is compiled as static binary, so it doesn’t have many runtime dependencies. It does require user namespaces to be properly set up, which allows Vagga to create and administer containers without having root privlege. This is increasingly available in modern distributions but may need to be enabled manually.
the
newuidmap
,newgidmap
binaries are required (either fromshadow
oruidmap
package)known exception for Archlinux: ensure
CONFIG_USER_NS=y
enabled in kernel. Default kernel doesn’t contain it, you can check it with:$ zgrep CONFIG_USER_NS /proc/config.gz
See Arch Linux
known exception for Debian and Fedora: some distributions disable unprivileged user namespaces by default. You can check with:
$ sysctl kernel.unprivileged_userns_clone kernel.unprivileged_userns_clone = 1
or you may get:
$ sysctl kernel.unprivileged_userns_clone sysctl: cannot stat /proc/sys/kernel/unprivileged_userns_clone: No such file or directory
Either one is a valid outcome.
In case you’ve got
kernel.unprivileged_userns_clone = 0
, use something along the lines of:$ sudo sysctl -w kernel.unprivileged_userns_clone=1 kernel.unprivileged_userns_clone = 1 # make available on reboot $ echo kernel.unprivileged_userns_clone=1 | \ sudo tee /etc/sysctl.d/50-unprivleged-userns-clone.conf kernel.unprivileged_userns_clone=1
/etc/subuid
and/etc/subgid
should be set up. Usually you need at least 65536 subusers. This will be setup automatically byuseradd
in new distributions. Seeman subuid
if not. To check:$ grep -w $(whoami) /etc/sub[ug]id /etc/subgid:<you>:689824:65536 /etc/subuid:<you>:689824:65536
The only other optional dependency is iptables
in case you will be doing
network tolerance testing.
See instructions specific for your distribution below.
Ubuntu¶
To install from vagga’s repository just add the following to sources.list:
deb http://ubuntu.zerogw.com vagga main
The process of installation looks like the following:
$ echo 'deb http://ubuntu.zerogw.com vagga main' | sudo tee /etc/apt/sources.list.d/vagga.list
deb http://ubuntu.zerogw.com vagga main
$ sudo apt-get update
[.. snip ..]
Get:10 http://ubuntu.zerogw.com vagga/main amd64 Packages [365 B]
[.. snip ..]
Fetched 9,215 kB in 17s (532 kB/s)
Reading package lists... Done
$ sudo apt-get install vagga
Reading package lists... Done
Building dependency tree
Reading state information... Done
The following NEW packages will be installed:
vagga
0 upgraded, 1 newly installed, 0 to remove and 113 not upgraded.
Need to get 873 kB of archives.
After this operation, 4,415 kB of additional disk space will be used.
WARNING: The following packages cannot be authenticated!
vagga
Install these packages without verification? [y/N] y
Get:1 http://ubuntu.zerogw.com/ vagga/main vagga amd64 0.1.0-2-g8b8c454-1 [873 kB]
Fetched 873 kB in 2s (343 kB/s)
Selecting previously unselected package vagga.
(Reading database ... 60919 files and directories currently installed.)
Preparing to unpack .../vagga_0.1.0-2-g8b8c454-1_amd64.deb ...
Unpacking vagga (0.1.0-2-g8b8c454-1) ...
Setting up vagga (0.1.0-2-g8b8c454-1) ...
Now vagga is ready to go.
Note
If you are courageous enough, you may try to use vagga-testing
repository to get new versions faster:
deb http://ubuntu.zerogw.com vagga-testing main
It’s build right from git “master” branch and we are trying to keep “master” branch stable.
Ubuntu: Old Releases (precise, 12.04)¶
For old ubuntu you need uidmap. It has no dependencies. So if your ubuntu release doesn’t have uidmap package (as 12.04 does), just fetch it from newer ubuntu release:
$ wget http://gr.archive.ubuntu.com/ubuntu/pool/main/s/shadow/uidmap_4.1.5.1-1ubuntu9_amd64.deb
$ sudo dpkg -i uidmap_4.1.5.1-1ubuntu9_amd64.deb
Then run same sequence of commands, you run for more recent releases:
$ echo 'deb http://ubuntu.zerogw.com vagga main' | sudo tee /etc/apt/sources.list.d/vagga.list
$ sudo apt-get update
$ sudo apt-get install vagga
If your ubuntu is older, or you upgraded it without recreating a user, you
need to fill in /etc/subuid
and /etc/subgid
. Command should be similar
to the following:
$ echo "$(id -un):100000:65536" | sudo tee /etc/subuid
$ echo "$(id -un):100000:65536" | sudo tee /etc/subgid
Or alternatively you may edit files by hand.
Now your vagga is ready to go.
Arch Linux¶
Default Arch Linux kernel doesn’t contain CONFIG_USER_NS=y
in configuration, you can check it with:
$ zgrep CONFIG_USER_NS /proc/config.gz
You may use binary package from authors of vagga, by adding the following
to /etc/pacman.conf
:
[linux-user-ns]
SigLevel = Never
Server = http://files.zerogw.com/arch-kernel/$arch
Note
alternatively you may use a package from AUR:
$ yaourt -S linux-user-ns-enabled
Package is based on core/linux
package and differ only with
CONFIG_USER_NS
option. After it’s compiled, update your bootloader
config, for GRUB it’s probably:
grub-mkconfig -o /boot/grub/grub.cfg
Warning
After installing a custom kernel you need to rebuild all the
custom kernel modules. This is usually achieved by installing *-dkms
variant of the package and systemctl enable dkms
. More about DKMS is
in Arch Linux wiki.
Then reboot your machine and choose linux-user-ns-enabled
kernel
at grub prompt. After boot, check it with uname -a
(you should have
text linux-user-ns-enabled
in the output).
Note
TODO how to make it default boot option in grub?
Installing vagga from binary archive using AUR package (please note that vagga-bin located in new AUR4 repository so it should be activated in your system):
$ yaourt -S vagga-bin
If your shadow
package is older than 4.1.5
, or you upgraded it without recreating a user, after installation you may need to fill in /etc/subuid
and /etc/subgid
. You can check if you need it with:
$ grep $(id -un) /etc/sub[ug]id
If output is empty, you have to modify these files. Command should be similar to the following:
$ echo "$(id -un):100000:65536" | sudo tee -a /etc/subuid
$ echo "$(id -un):100000:65536" | sudo tee -a /etc/subgid
Building From Source¶
The only supported way to build from source is to build with vagga. It’s as
easy as installing vagga and running vagga make
inside the the clone of a
vagga repository.
Note
First build of vagga is very slow because it needs to build rust with musl standard library. When I say slow, I mean it takes about 1 (on fast i7) to 4 hours and more on a laptop. Subsequent builds are much faster (less than minute on my laptop).
Alternatively you can run vagga cached-make
instead of vagga make
.
This downloads pre-built image that we use to run in Travis CI. This may be
changed in future.
There is also a vagga build-packages
command which builds ubuntu and binary
package and puts them into dist/
.
To install run:
$ make install
or just (in case you don’t have make
in host system):
$ ./install.sh
Both support PREFIX
and DESTDIR
environment variables.
Note
We stopped supporting out-of-container build because rust with musl
is just too hard to build. In case you are brave enough, just look at
vagga.yaml
in the repository. It’s pretty easy to follow and there is
everything needed to build rust-musl with dependencies.