Copyright 2016 by Assured Information Security, Inc. Created by Jean-Edouard Lejosne <lejosnej@ainfosec.com>. This work is licensed under the Creative Commons Attribution 4.0 International License. To view a copy of this license, visit http://creativecommons.org/licenses/by/4.0/.


OpenXT version 6 and later include build scripts that help you setup a build environment and build OpenXT.

The scripts use LXC Containers for the Linux bits (OpenEmbedded-based OpenXT core, Debian tools and Centos tools), and a KVM VM for the Windows tools.

It is recommended to use a recent 64 bits Debian version (Jessie / Stretch) as the host OS because:

The setup step happens only once, as root, to install packages, create containers/VMs and more.

The build step should be run each time you need a new build.


Table of Contents:

Setup

Install Git

$ apt-get install git

If you are using Ubuntu 14.04 or above, you'll also need the package `lxc-templates`.

Clone openxt.git

The first build scripts exist in openxt.git (along with this README.md file), so clone that:

$ git clone git://github.com/OpenXT/openxt.git

You can of course clone your own fork. Be aware that there are another approximately 60 OpenXT repositories that will be checked out next.

Configuring the environment

Change to the openxt/build-scripts directory.

Run the following to see the list of options:

$ ./setup.sh -h

setup.sh will install the Linux containers package (lxc) and use it to create containers that will become potentially quite big (a whole build can take almost 100GB of disk space (without the WIndows VM)).

By default, lxc creates all the containers in /var/lib/lxc. If the partition for that directory is too small, the build will fail.

To change the location of the containers to, for example, /home/lxc, do the following (as root):

$ apt-get install lxc
$ echo "lxc.lxcpath = /home/lxc" > /etc/lxc/lxc.conf

Also, make sure that the lxc.lxcpath exists.


If using Debian Buster (10), make sure your kernel is booted with the option "vsyscall=emulate".

For more information, see: https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=875981


Run the following as root or with sudo:

$ ./setup.sh [-u user] [...]

If you want your setup to include a Windows VM, use the -w options, as documented below.

As setup.sh is re-entrant, you can always run it again later with the -w option if you don't want to bother with it for now.

The optional user parameter specifies the host user the build will run as, that may or may not already exist. If one is not supplied a user named openxt will be created. If the openxt user is created, you will be prompted to set a password.

The script is re-entrant, but in the ideal case it will have to be called only once for the life of the build machine.

This will setup all the containers and configure the build environment.

The end result consists of:

Setting up the Windows VM

The build scripts can also be used to setup a Windows VM (using KVM), and automatically build the tools in it as part of the main build process.

To add a Windows VM to the 3 containers, provide the script with the URL of a Windows 7/10 iso using the -w option.

For example:

$ ./setup.sh -w http://inyourdreams.microsoft.com/win10x86.iso

The Windows setup process requires quite a lot of user interaction, since the scripts can't control anything that happens in Windows, at least until the Build Daemon is installed.

To setup a Windows virtual machine as part of the setup step of the build scripts, just use the -w option, followed by the URL of a Windows ISO.

setup.sh will setup Windows last. Once the script reaches that point, it tell you to VNC to it to set it up.

Here's what to do:

Under Linux;
$ sudo apt-get install vncviewer
$ vncviewer <Windows VM>:<port>     # The script should tell you what the port is

Under Windows;
- You can use any VNC viewer, such as the one included as a Google Chrome app. Search for "VNC Viewer for Google Chrome" under Apps.

Once VNC is connected;

Build

Running the build

Run the build script as the build user from above:

$ ./build.sh

or (better):

$ screen ./build.sh

When the script is finished the build is done. The build output can be found in a directory named after the date (example: /home/openxt/160301-1/).

If a Windows VM was created as part of the setup, build.sh will use it to build the Windows guest tools.

Note: if the build fails, just run build.sh again, using the -n option to specify the build number. For example: ./build.sh -n 160301-1

Note: build.sh uses the external fetch.sh script to update the git mirrors and start the git service if needed.

The build inside the containers will be done against your local git mirror. Running git pull inside the containers will pull from the mirror, not from the OpenXT GitHub repositories.

You should run fetch.sh manually after each reboot (to start the git service),  and whenever you need the mirror updated.

Install

Just use the build output to install OpenXT the usual way, whether using the ISO or the netboot files.

In addition to that, there will be a Debian repository and an RPM repository that can be put on a web server and used to install the tools.

For example:

More information

Setup Step Details

The scripts have been mostly tested on a fresh install of Debian Jessie 64 bits, but other (Debian-based) configurations should work too.

In more details, the script will:

Once that's done, the main setup script will then create LXC containers for the user, and use container-specific setup.sh scripts to configure them.

3 containers will be created:

Note: In the main setup.sh, each container creation is a one-line function call that can be commented out if the user doesn't want that particular container.

A separate git mirror will also be created for the user. build.sh will fetch it each time it's called.

Note: once the user has a build environment setup, it's important that he fetches the git mirrors before trying to pull anything in the build tree, to get the most recent version of the repository.

setup.sh will finally copy build.sh to the user's home directory.

Build Step Details

A successfully setup user can run ./build.sh to start a build. That script will:

After about 5 to 8 hours, if everything went well, there will be an OpenXT build in a directory named after the current date.

Note: In the main build.sh, each container build is a one-line function call that can be commented out if the user doesn't want to build that particular container.