OverC Overview ------------------ OverC is composed of building blocks (cubes) that implement a set of related functionality. The current cubes are: - dom0: provides control services to the platform and is responsible for launching other containers in the system. Dom0 is not manipulated by non admin users. - cube-vrf: provides virtual routing and forwarding (vrf) functions to the system. By running an OpenVSwitch (ovs) bridge along with other networking services. Containers will 'insert' one end of a veth pair into the cube-vrf, via startup hooks, to join the cube LAN to provide minimal networking to containers. - cube-desktop: provides full 'enterprise' functionality. This includes man pages, development tools, graphical desktop, etc. This domain is the primary environment for most users. - cube-server: provides a full featured, headless server environment. This is similar to cube-desktop, without graphics. OverC also has two essential image types, that provide a foundation for the container runtimes. These are: - cube-builder: This is the image which lists all the packages required to boot the platform. cube-builder is also capable of self hosting and building the platform itself. Please add following line in local.conf before building kernel for cube-builder: OVERC_PLATFORM_TUNING += "builder" - cube-essential: This is a minimal runtime which is used for both the installer and cube-essential in the fully assembled system. OverC build ----------- Modify local.conf with following settings: # build the cube distro DISTRO ?= "overc" # build the genericx86 machine, ussing the common-pc-64 branch MACHINE="genericx86-64" KMACHINE:genericx86-64 ?= "common-pc-64" # IMPORTANT: remove 'image-mklibs image-prelink' from the default # user classes. They break lxc-autostart. USER_CLASSES ?= "buildstats" Clone the layers described in the meta-overc/README, and build the images mentioned in the overview: % bitbake cube-dom0 cube-vrf cube-desktop cube-essential cube-builder This will take some time, since multiple images and configurations are being build and assembled. Note: you can also find images at: http://openlinux.windriver.com/overc/images Once the build (or download) completes, the build artifacts must be assembled into an installer image (see the following sections). By default, rootfs for cube-essential is in read-only mode, changes on rootfs will lead failure or lost after system reboot. User may change read/write attribute of rootfs when system running after login to cube-essenial as root user. To build a read-write rootfs for cube-essential, please add following line in local.conf before building cube-essential: OVERC_ESSENTIAL_MODE = "read-write" OverC installer --------------- The OverC installer must be assembled from build artifacts, and provides a bootable USB stick that is capable of installing to a hard disk on the target system. It also completes required installation and configuration of the components that make up the core system (dom0, cube-vrf, cube-desktop, essential). The OverC installer is available from the following repository: https://github.com/OverC/overc-installer.git Once cloned, the installer must be configured for your target device (Sample configurations are provided). The following sample shows how to create an installer on a network block device, with the outputs of a typical OverC build. Changing the target device to a USB stick results in an installer that boots and runs on most x86 targets. % WORKDIR= % CLONEDIR= #e.g. CLONEDIR=$WORKDIR % cd $CLONEDIR % git clone git://github.com/OverC/overc-installer.git % mkdir -p $WORKDIR/usbhdinstaller % cd $WORKDIR/usbhdinstaller % mkdir .overc % cp $CLONEDIR/overc-installer/config/config-usb-cube.sh.sample .overc/config-usb-cube.sh % cp $CLONEDIR/overc-installer/config/config-usb.sh.sample .overc/config-usb.sh Edit the variables in config-usb.sh to suit the build and desired installation. In particular: ARTIFACTS_DIR: set this to the directory containing the built images and kernel e.g. $WORKDIR/tmp/deploy/images/genericx86-64 ** NOTE: ARTIFACTS_DIR defined in config-usb.sh will be ignored if ./cubeit is called with --artifacts And confirm that the following outputs exist in the artifacts directory: INSTALL_KERNEL="${ARTIFACTS_DIR}/bzImage" INSTALL_ROOTFS="${ARTIFACTS_DIR}/cube-essential-genericx86-64.tar.bz2" INSTALL_INITRAMFS="${ARTIFACTS_DIR}/cube-builder-initramfs-genericx86-64.cpio.gz" One other important file to modify is the grub configuration for the bootable USB device. It is controlled by the following variable: INSTALL_GRUBUSBCFG="grub-usb.cfg" That file, located in files/grub-usb.cfg in the installer tree is used by grub when booting, and must be tailored to the target device AND version of grub. Copy the grub configuration to ~/.overc/ and edit to suit your device(s). ** NOTE: the grub installed on the machine writing the USB stick is used to populate the bootable device. % cp $CLONEDIR/overc-installer/files/grub-usb.cfg $WORKDIR/usbhdinstaller/.overc The sample grub configuration files are for grub2, so if the machine creating the stick is not grub2, they will not work. The only current solution is to install grub2, or modify the files to suit your version of grub. Finally, edit config-usb-cube.sh to list the containers and essential rootfs that is to be installed. This is typically: HDINSTALL_ROOTFS="${ARTIFACTS_DIR}/cube-essential-genericx86-64.tar.bz2" HDINSTALL_CONTAINERS="${ARTIFACTS_DIR}/cube-dom0-genericx86-64.tar.bz2 \ ${ARTIFACTS_DIR}/cube-desktop-genericx86-64.tar.bz2" At this point we have the payload to create a bootable USB disk prepared. The scripts (or applications) that perform the final install to the target device are found in the installers/ subdirectory. The installers can be simple, or complex, and should be edited to suit the desired target runtime. ** Note **: carefully inspect any sample or existing installer that is placed on the USB installer, since they may not be appropriate for your target device (and hence remove / wipe data). cube-install.sh is capable of partitioning a device, installing the essential rootfs, configuring grub, extracting container payloads and rebooting the device. It serves as a good example for other custom installers. Once the installer(s) have been modified to suit the target device, the following example command produces a bootable nbd USB device (assuming that a nbd has been created properly started): % BLOCK_DEV= # e.g. /dev/nbd0 or /dev/sdb etc. % sudo $CLONEDIR/overc-installer/sbin/cubeit --config $WORKDIR/usbhdinstaller/.overc/config-usb-cube.sh --artifacts $ARTIFACTS_DIR $BLOCK_DEV We now have a bootable device, with an embedded installer + installation payload. NOTES: * The containers listed in HDINSTALL_CONTAINERS can have attributes that instruct the installer to perform configuration steps. net=1 : the container is the network prime console : the container should be granted (physical) console access vty= : allocate/reserver VT for the container * To pass devices through to the network prime, specify them via the following variables: NETWORK_DEVICE="enp0s3" or use wild cards NETWORK_DEVICE="en+ wl+ eth+" And substitute the device that applies to your platform OverC installation ------------------ Once a bootable installer has been created, insert it into the target and boot. The default USB bootable image runs cube-essential, with the login of root/root. After logging into the bootable device, the installer should be run to move artifacts to their final destination device. In our cube-install.sh example from above, the following commands should be run (assuming an installation to a second virtual disk): % cd /opt/installer/ % ./sbin/cubeit-installer images/cube-essential-* vdb #or e.g. sda for hard drive ** Note: The cube installer will destroy all data on the target device, since it re-partitions, create filesystems, installs the boot image and the rootfs + container filesystems. Do not run it against a device with data you cannot afford to lose. ** Note: To create the root filesystem in btrfs, add -b option to cube-install.sh % ./sbin/cubeit-installer -b images/cube-essential-* vdb Once this completes, the device is powered off, and is ready with the OverC runtime.