vpsAdminOS

vpsAdminOS is a small OS serving as a host for unprivileged Linux system containers. It is based on NixOS and not-os. It is designed to run full distributions inside unprivileged containers which look and feel as much as a virtual machine as possible.

vpsAdminOS is developed and used in production by vpsFree.cz, a non-profit organization which provides virtual servers to its members. See vpsfree-cz-configuration for example cluster configuration.

Links

• IRC: #vpsadminos @ irc.libera.chat
• Documentation: https://vpsadminos.org/
• Man pages: https://man.vpsadminos.org/
• OS and program references: https://ref.vpsadminos.org/
• ISO images: https://iso.vpsadminos.org/

Components

vpsAdminOS uses:

• LTS kernel with a mix of out-of-tree patches to improve container experience,
• runit as an init system,
• ZFS for storage,
• our own tools for system container management called osctl,
• LXC is used to run the containers,
• BIRD for network routing.

Building OS

Our kernel live-patch facility requires ccache to build the OS.

git clone https://github.com/vpsfreecz/vpsadminos/
cd vpsadminos

vpsAdminOS is developed on top of the latest NixOS release and pins nixpkgs in flake.lock, so you do not need to set NIX_PATH. Ensure flakes are enabled (Nix >= 2.4 or experimental-features = nix-command flakes in nix.conf).

vpsAdminOS can now be built and run:

# Build the OS
make

# Run under qemu
make qemu

The QEMU runner creates two disk images - sda.img and sdb.img which are added as QEMU ATA drives and can be used to create a mirrored ZFS pool that persists across reboots.

Explicit ZFS Full Suite

OpenZFS full-suite execution is available as an explicit test-runner tag and is not part of default -t ci runs.

# Full profile (long run)
./run-zfs-full-suite.sh

# Quicker profiles
PROFILE=sanity ./run-zfs-full-suite.sh
PROFILE=smoke ./run-zfs-full-suite.sh

# Start multiple runs in parallel by using unique state dirs/run ids
RUN_ID=zfs-full-a ./run-zfs-full-suite.sh
RUN_ID=zfs-full-b ./run-zfs-full-suite.sh

Usage

# Login via ssh or use qemu terminal with autologin
ssh -p 2222 localhost

# Configure osctld:
osctl pool install tank

# Create a container:
osctl ct new --distribution alpine myct01

# Configure container networking:
# Bridged veth
osctl ct netif new bridge --link lxcbr0 myct01 eth0

# Routed veth
osctl ct netif new routed myct01 eth1
osctl ct netif ip add myct01 eth1 1.2.3.4/32

# Start the container:
osctl ct start myct01

# Work with containers:
osctl ct ls
osctl ct attach myct01
osctl ct console myct01
osctl ct exec myct01 ip addr

# More information:
man osctl

# https://vpsadminos.org/user-guide/setup/
# https://vpsadminos.org/containers/administration/

Binary cache

vpsAdminOS has its own binary cache which contains builds of vpsAdminOS with the current NixOS stable branch. Using it can save a lot of time building the kernel.

{ config, ... }:
{
  nix.settings = {
    substituters = [ "https://cache.vpsadminos.org" ];
    trusted-public-keys = [ "cache.vpsadminos.org:wpIJlNZQIhS+0gFf1U3MC9sLZdLW3sh5qakOWGDoDrE=" ];

    # Enable fallback in case the binary cache is unreachable
    fallback = true;
    connect-timeout = 15;
  };
}

Docs

• vpsAdminOS documentation
• Manual pages
• Reference documentation
• https://linuxcontainers.org/