# guest-images

**Repository Path**: cherry_wb/guest-images

## Basic Information

- **Project Name**: guest-images
- **Description**: Scripts to automatically create VM images
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2020-01-09
- **Last Updated**: 2024-06-05

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

Automated Guest Image Creation Tools
====================================

This repository contains a Makefile that allows building guest images suitable for running in S2E. The creation process
is fully automated.

# Installing dependencies

```
sudo apt-get install libguestfs-tools genisoimage python-pip python-magic xz-utils docker.io p7zip-full pxz libhivex-bin fuse jigdo-file
sudo apt-get build-dep fakeroot linux-image$(uname -r)
sudo pip install jinja2

# This is necessary for guestfish to work
sudo chmod +r /boot/vmlinuz*

# Re-login after running these commands
sudo usermod -a -G docker $(whoami)
sudo usermod -a -G kvm $(whoami)
```

# Building S2E

Build and install S2E into some folder (e.g., ```/home/user/s2e/build/opt/```).
Please refer to S2E build instructions for details.

# Checking out the kernel repository
```
cd /home/user
git clone https://github.com/s2e/s2e-linux-kernel
```

# Building Linux images

```
git clone https://github.com/s2e/guest-images
cd /home/user/s2e/guest-images

S2E_INSTALL_ROOT=/home/user/s2e/build/opt \
  S2E_LINUX_KERNELS_ROOT=/home/user/s2e-linux-kernel \
  make linux -j3
```

The build should take around 30 minutes. The images will be placed in the ```output``` directory, which looks like this:

```
./debian-8.7.1-i386/image.json
./debian-8.7.1-i386/image.raw.s2e
./debian-8.7.1-i386/image.raw.s2e.ready

./debian-8.7.1-x86_64/image.json
./debian-8.7.1-x86_64/image.raw.s2e
./debian-8.7.1-x86_64/image.raw.s2e.ready

./cgc_debian-8.7.1-i386/image.json
./cgc_debian-8.7.1-i386/image.raw.s2e
./cgc_debian-8.7.1-i386/image.raw.s2e.ready
```

Each build is composed of a json file that describes how to run the image, the image itself, as well as a "ready"
snapshot.

The build process also creates ```.stamps``` and ```.tmp-output```. The first contains stamp files to keep track of
which parts have been built, while the second contains intermediate build output (e.g., kernel images and ISO files).

# Building Windows images

First, you need to get the ISO file for the Windows version that you want to install. You can download these images from
MSDN. The hash and the name of the ISO is specified in the  ``images.json`` file. You can use the hash to make sure that
you downloaded the right version. Place the downloaded file in the ``iso`` folder.

Do not forget to update the ``product_key`` value in the ``images.json`` file. Some versions of Windows require one
for installation (e.g., XP). Other versions install without one. You should not need to activate Windows once a snapshot
is taken (time is frozen and the guest has no Internet access). Make sure you have the required licenses to install
and use Windows this way.

The ``images.json`` file lists all Windows versions that S2E officially supports. Other images may work too but we have
not tested them. If you want to add support for new images, you may need to also update ``s2e.sys`` in the
``guest-tools`` repository in order to support the different kernels. This may not be needed if the Windows version you
need uses the exact same kernel as an already supported one. Please refer to the documentation in ``guest-tools``.


```
cd /home/user/s2e/guest-images

mkdir iso && cd iso
# Download Windows ISO images (e.g., from MSDN)
# See images.json for details.
wget ...
cd ..

S2E_INSTALL_ROOT=/home/user/s2e/build/opt \
  S2E_LINUX_KERNELS_ROOT=/home/user/s2e-linux-kernel \
  make windows -j3
```

The installation process takes periodic screenshots that are stored in ``.tmp-output`` and ``output`` folders. Run
``find . -name *.png`` in order to locate them. Screenshots are useful for debugging, especially if you are adding
custom images.

You may add additional applications to the Windows images by following these steps:
- Add a rule to ``Makefile.windows`` in order to download the installer package. The package must allow unattended
  installation (i.e., not have any dialog prompts, reboot after install must be disabled)
- If you can't find a suitable installer package, you may also zip the app into a file to be placed into
  ``Windows/install_scripts/inst``.
- Add an installation script to ``Windows/install_scripts``. This can be as simple as invoking the installer or
  unzipping the package into the right destination.


# Customization and debugging

If something goes wrong, you may want to turn on graphics output. Open the makefile and comment out the ```GRAPHICS```
variable.

You may add additional packages to the base image by customizing the ```Linux/bootcd/preseed.cfg``` file.