{"id":18925289,"url":"https://github.com/s2e/guest-images","last_synced_at":"2025-07-28T17:07:43.654Z","repository":{"id":20120465,"uuid":"88266059","full_name":"S2E/guest-images","owner":"S2E","description":"Scripts to automatically create VM images","archived":false,"fork":false,"pushed_at":"2024-06-09T18:31:59.000Z","size":1958,"stargazers_count":14,"open_issues_count":1,"forks_count":19,"subscribers_count":7,"default_branch":"master","last_synced_at":"2025-04-15T15:11:35.442Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"PowerShell","has_issues":false,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/S2E.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":"vitalych","patreon":null,"open_collective":null,"ko_fi":null,"tidelift":null,"community_bridge":null,"liberapay":null,"issuehunt":null,"otechie":null,"custom":null}},"created_at":"2017-04-14T12:32:01.000Z","updated_at":"2024-06-09T18:32:01.000Z","dependencies_parsed_at":"2024-06-02T15:46:49.239Z","dependency_job_id":"b7fcddf5-94c4-468a-88fc-b2c3fd649b66","html_url":"https://github.com/S2E/guest-images","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/S2E/guest-images","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/S2E%2Fguest-images","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/S2E%2Fguest-images/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/S2E%2Fguest-images/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/S2E%2Fguest-images/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/S2E","download_url":"https://codeload.github.com/S2E/guest-images/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/S2E%2Fguest-images/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":267552097,"owners_count":24106000,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-07-28T02:00:09.689Z","response_time":68,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-08T11:10:29.934Z","updated_at":"2025-07-28T17:07:43.623Z","avatar_url":"https://github.com/S2E.png","language":"PowerShell","funding_links":["https://github.com/sponsors/vitalych"],"categories":[],"sub_categories":[],"readme":"Automated Guest Image Creation Tools\n====================================\n\nThis repository contains a Makefile that allows building guest images suitable for running in S2E. The creation process\nis fully automated.\n\nIt is recommended to use the ``s2e image_build`` command in order to build images instead of calling the makefiles\ndirectly. That command ensures that the makefile is called with the right arguments and that all requirements\nare met. Please refer to the S2E documentation on how to use ``s2e image_build``. This README provides a reference\nin case you want to modify the image build system or add new software to existing images.\n\n# Installation\n\n**It is recommended to use a file system that supports copy-on-write (XFS, ZFS, or BtrFS).** The image build system\ncopies images for intermediate build steps and copy-on-write will save you a lot of disk space.\n\n## Installing dependencies\n\n```\nsudo apt-get install libguestfs-tools genisoimage python-pip python-magic xz-utils docker.io p7zip-full pxz libhivex-bin fuse jigdo-file cloud-image-utils\nsudo apt-get build-dep fakeroot linux-image$(uname -r)\nsudo pip install jinja2\n\n# This is necessary for guestfish to work\nsudo chmod +r /boot/vmlinuz*\n\n# Re-login after running these commands\nsudo usermod -a -G docker $(whoami)\nsudo usermod -a -G kvm $(whoami)\n```\n\n## Building S2E\n\nBuild and install S2E into some folder (e.g., ```/home/user/s2e/build/opt/```).\nPlease refer to S2E build instructions for details.\n\n## Checking out the kernel repository\n```\ncd /home/user\ngit clone https://github.com/s2e/s2e-linux-kernel\n```\n\n## Checking out guest-images repository\n\n```\ncd /home/user\ngit clone https://github.com/s2e/guest-images\n```\n\n# Building images\n\n## Linux\n\n```\ncd /home/user/guest-images\n\nS2E_INSTALL_ROOT=/home/user/s2e/build/opt \\\n  S2E_LINUX_KERNELS_ROOT=/home/user/s2e-linux-kernel \\\n  make linux -j3\n```\n\nThe build should take around 30 minutes. The images will be placed in the ```output``` directory, which looks like this:\n\n```\n./debian-8.7.1-i386/image.json\n./debian-8.7.1-i386/image.raw.s2e\n./debian-8.7.1-i386/image.raw.s2e.ready\n\n./debian-8.7.1-x86_64/image.json\n./debian-8.7.1-x86_64/image.raw.s2e\n./debian-8.7.1-x86_64/image.raw.s2e.ready\n\n```\n\nEach build is composed of a json file that describes how to run the image, the image itself, as well as a \"ready\"\nsnapshot.\n\nThe build process also creates ```.stamps``` and ```.tmp-output```. The first contains stamp files to keep track of\nwhich parts have been built, while the second contains intermediate build output (e.g., kernel images and ISO files).\n\n## Windows\n\nFirst, you need to get the ISO file for the Windows version that you want to install. You can download these images from\nMSDN. The hash and the name of the ISO is specified in the  ``images.json`` file. You can use the hash to make sure that\nyou downloaded the right version. Place the downloaded file in the ``iso`` folder.\n\nDo not forget to update the ``product_key`` value in the ``images.json`` file. Some versions of Windows require one\nfor installation (e.g., XP). Other versions install without one. You should not need to activate Windows once a snapshot\nis taken (time is frozen and the guest has no Internet access). Make sure you have the required licenses to install\nand use Windows this way.\n\nThe ``images.json`` file lists all Windows versions that S2E officially supports. Other images may work too but we have\nnot tested them. If you want to add support for new images, you may need to also update ``s2e.sys`` in the\n``guest-tools`` repository in order to support the different kernels. This may not be needed if the Windows version you\nneed uses the exact same kernel as an already supported one. Please refer to the documentation in ``guest-tools``.\n\nBuild scripts for Windows XP and Windows 7 install service packs and updates up to January 2016 and 2020 respectively.\n\n```\ncd /home/user/guest-images\n\nmkdir iso \u0026\u0026 cd iso\n# Download Windows ISO images (e.g., from MSDN)\n# See images.json for details.\nwget ...\ncd ..\n\nS2E_INSTALL_ROOT=/home/user/s2e/build/opt \\\n  S2E_LINUX_KERNELS_ROOT=/home/user/s2e-linux-kernel \\\n  make windows -j3\n```\n\n## Building Microsoft Office images\n\nThis sections explains how to build Microsoft Office installation disks.\nThese disks must be placed in the ``iso`` folder specified with ``s2e image_build --iso-dir /path/to/isos``.\nYou will need 32-bit versions of Office. 64-bit versions should work too, but we did not test them.\n\n### Office 2019\n\nYou will need to build the ISO image manually using the Microsoft Office Deployment Tools (ODT). You do not need\nMSDN access for this version of Office. The scripts will install the Volume License version.\n\n1. Find a Windows 10 machine / VM\n2. Download [ODT](https://download.microsoft.com/download/2/7/A/27AF1BE6-DD20-4CB4-B154-EBAB8A7D4A7E/officedeploymenttool_12624-20320.exe\u003e)\n3. Run the ODT setup file, decompress it to ``C:\\ODT``\n4. Copy the Office 2019 configuration file located in ``Windows/install_scripts/50_office/config2019.xml`` to\n   ``C:\\ODT`` on the Windows machine.\n4. Open ``cmd.exe``\n5. Run ``md C:\\Office2019``. ODT will download Office installation files into this folder\n6. ``config2019.xml`` expects the download folder to be in drive ``D:\\``.\n   Run ``subst D:\\ C:\\Office2019``. This will mount the folder as ``D:\\``.\n   You can also edit ``config2019.xml`` to point to ``C:\\Office2019`` instead.\n5. Run ``C:\\odt\\setup.exe /download C:\\ODT\\config2019.xml``\n6. Wait for the download to complete. Check that ``C:\\Office2019`` contains the installation files.\n7. Create an ISO image out of the contents of ``C:\\Office2019``.\n   You can do so by copying ``C:\\Office2019`` to a Linux machine and then run\n   ``genisoimage --iso-level 2 -flDJR -o office2019.iso Office2019/``\n8. Mount the ISO file and check that the following path is present on the image:\n   ``/Office/Data/16.0.10358.20061/`` (i.e., there should be an ``Office`` folder in the root of the drive).\n9. Place the ISO in the ``iso`` directory.\n\n### Office 2010, 2013, 2016\n\nYou can download the ISO files for these versions of Office from MSDN. Choose the Office Pro Plus x86 edition.\nRefer to ``apps.json`` for the exact name of the ISO file to download. Place the ISO in the ``iso`` directory that\nyou passed to ``s2e image_build``.\n\nIf you have access to a volume license edition of Office, please choose it instead, as it will not show an activation\nwindow every time an app is started. Except for Office 2010, you should not need product keys to install Office,\nas they have a grace period of a few days before requiring activation. The image building scripts create VM snapshots\nwith frozen time, so expiration should not be an issue.\n\nOffice 2010 may come as a self-contained executable file on MSDN. In this case, extract this file into a folder\nand create an ISO out of that folder.\n\n### How do I tweak the Office installation?\n\nOffice installation scripts are located in ``Windows/install_scripts/50_office``. You will find the following files:\n- An XML/MSP file for each supported edition. This file contains the unattended installation settings.\n  The MSP file for Office 2016 is generated with the OCT tool that you can find on the ISO file.\n  This tool is only available on Volume License edition.\n- ``launch.bat.template`` invokes the installer.\n- ``precheck.sh`` validates the ISO file.\n- ``postcheck.sh`` verifies that the installation completed properly.\n\nYou can modify these files to suit your needs.\n\n# Customizing images\n\n## Linux\n\nYou can add additional packages to the base image by customizing the ```Linux/bootcd/preseed.cfg``` file.\nAlternatively, you can modify ``Linux/s2e_home/launch.sh``. The VM has Internet access, so you can get any\nadditional packages you need from that script.\n\n## Windows\n\nImage building is divided into steps. Each step installs one or more software packages, then reboots the VM.\nThe last step boots the VM in TCG mode and takes a snapshot.\n\nEach step mounts two CD drives:\n\n1. The drive ``D:\\`` contains all software packages to be installed (``00_software.iso``).\n2. The drive ``E:\\`` contains the scripts to install desired packages (e.g., ``05_dotnet.iso``).\n   This drive is built from the folders in ``Windows/install_scripts``.\n\nYou may add additional applications to the Windows images by following these steps:\n\n1. Add a rule to ``Makefile.windows.apps`` in order to download the installer package. The package must allow unattended\n   installation (i.e., not have any dialog prompts, reboot after install must be disabled). The package will be\n   automatically added to the ``00_software.iso`` disk.\n\n2. Instead of downloading new software, you can place it in one of the installation folders\n   (e.g., ``07_install_software``). If your software doesn't come with an installer, you can zip its files in an archive\n   instead.\n\n3. Modify the right ``launch.bat`` file to start the installer. In most cases, it will be\n   ``07_install_software/launch.bat``. If you use a zip archive, call ``7z`` to decompress it. Refer to existing scripts\n   for examples of how to do it.\n\nThe makefile detects modifications and additions to the folders in ``install_scripts``, and will automatically start the\ninstallation from the updated step in order to minimize image build time.\n\nUnlike Linux images, Windows VMs do not have Internet access. You must provide all additional software through ISO\nimages as explained above.\n\nNote that by default, the makefile does not create intermediate copies of the guest image for each installation step in\norder to save disk space. In practice, if you modify, e.g, the step ``07_install_software``, the guest image that will\nbe used to re-run this step will already contain changes done by subsequent steps. Read the next section to learn how to\nmodify this behavior.\n\nThe current image build system does not natively support software that comes on an ISO image (e.g., Microsoft Office).\nYou must modify the makefile to accommodate that (e.g., add an additional virtual drive with the desired software).\n\n# Installing Windows applications\n\nFollow these steps:\n\n1. Get the ISO file of your app. If it does not come as an ISO file, e.g., if it is an ``exe`` or ``msi`` file,\n   package that file into an ISO with the ``geniso`` tool.\n2. Create an entry in ``app.json``. You can follow the same template as, e.g., Office.\n3. Create a directory with installation scripts in ``Windows/install_scripts``.\n   Specify that directory in the ``scripts_dir`` field in ``apps.json``.\n4. Create a ``launch.bat.template`` file. This is the Windows batch file template that will run the installer.\n   The template uses the Jinja2 syntax and has the following variables: ``app_name``, ``product_key``, and ``guestfs``.\n   You may use the first two for configuration purposes. See the MS Office installation scripts for a complete\n   example of how to use them.\n\n    ```\n    :: launch.bat.template\n    :: This script is called twice: once to install the app and once after\n    :: rebooting to accommodate apps that require a reboot to be usable.\n    :: Therefore, we must skip the installation if we detect that the app\n    :: is already installed. This is dependent on your particular app, so you\n    :: should modify the following two lines accordingly.\n    if exist \"%SystemDrive%\\Program Files (x86)\\MyApp\" goto end\n    if exist \"%SystemDrive%\\Program Files\\MyApp\" goto end\n\n    :: This is your installer on the ISO file. Make sure that setup.exe\n    :: does not return until the installation actually completes. If you have\n    :: an MSI file, run it with msiexec.\n    :: The ISO file that you created for your app is mounted on D:\\\n    :: This installation script is located in E:\\\n    d:\\setup.exe\n\n    :: This must be present in order to copy the newly installed binaries to the host.\n    :: S2E plugins may need to access them and some of them won't work if the\n    :: binaries are missing. You should not change this line.\n    c:\\Python27\\python.exe e:\\upload_guestfs.py e:\\guest_files.txt 10.0.2.100:1234 {{ guestfs }} c:\\\n\n    :end\n    timeout 20\n    shutdown /r /t 0\n    ```\n\n5. Create pre-check and post-check scripts. The pre-check verifies that the ISO file contains the right software\n   (e.g., to avoid installing the wrong software by mistake), while the post-check verifies that the software was\n   properly installed. This is typically done by looking for installed files in the ``guestfs`` directory.\n\n\n# Debugging\n\nIf something goes wrong, proceed as follows:\n\n* If something gets stuck or crashes, look at screenshots. They may contain error messages or display blocking message\n  boxes. The installation process takes screenshots every few seconds and stores them in the ``.tmp-output``\n  directory of each image. Run ``find . -name *.png`` to find them.\n\n* Turn on graphics output. Open the makefile and comment out the ```GRAPHICS``` variable.\n  If you use ``s2e image_build``, add the ``-g`` option. This is convenient if you modify existing build scripts\n  and want to monitor the installation as it goes.\n\n* Look at the serial output. Most installation steps redirect stdout / stderr to the serial port, which is recorded\n  in ``*_serial.txt`` files.\n\n* Check that Virtual Box, VMware, or any other virtualization software is not running. It interferes with KVM.\n  This should not be a problem if you use ``s2e image_build``, which checks this before starting the build process.\n\n* If you need to debug an intermediate installation step on Windows, set ```DEBUG_INTERMEDIATE_RULES``` to 1.\n  The makefile will checkpoint the disk images after each build step. If you abort the build, it will restart\n  the aborted step using a fresh image copy from the previous build step.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fs2e%2Fguest-images","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fs2e%2Fguest-images","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fs2e%2Fguest-images/lists"}