Quick Start Guide

• Install Prerequisites
• Clone CBL-Mariner
• Build and Boot an Image
  • VHDX and VHD Images
  • ISO Image

Install Prerequisites

Install prerequisites here.

Clone CBL-Mariner

From a bash terminal window, clone the CBL-Mariner Repository and check-out a stable build.

# Clone the CBL-Mariner repo
git clone https://github.com/microsoft/CBL-Mariner.git
cd CBL-Mariner

# Sync to the latest stable build
git checkout 2.0-stable

Build and Boot an Image

VHDX and VHD images

The following builds a bootable, VHDX or VHD CBL-Mariner image from precompiled RPMs in the CBL-Mariner package repository at https://packages.microsoft.com/cbl-mariner/2.0/prod/.

No user account is provisioned by default. To sign-in to these images, the sample meta-user-data.iso image must also be built and installed in your VM's CD drive. The cloud-init service will detect the iso and provision a user account and password.

Build a VHD or VHDX Image

# Switch to the toolkit folder
cd toolkit

# Build VHDX Image
# Image is placed in ../out/images/core-efi
sudo make image REBUILD_TOOLS=y REBUILD_PACKAGES=n CONFIG_FILE=./imageconfigs/core-efi.json

# Build VHD Image
# Image is placed in ../out/images/core-legacy
sudo make image REBUILD_TOOLS=y REBUILD_PACKAGES=n CONFIG_FILE=./imageconfigs/core-legacy.json

Build the cloud-init configuration image

Note that the cloud-init configuration file does not build by default. You will need to edit it to set a username and password or SSH Key. The file is located in ./resources/assets/meta-user-data/user-data.

# Build the cloud-init configuration image
# The output image is ../out/images/meta-user-data.iso
sudo make meta-user-data

Copy VHD(X) and ISO Images to Your VM Host Machine

Copy your binary image(s) to your VM Host Machine using your preferred technique.

Create VHD(X) Virtual Machine with Hyper-V

1. From Hyper-V Select Action->New->Virtual Machine.
2. Provide a name for your VM and press Next >.
3. For VHD select Generation 1. For VHDX select Generation 2, then press Next >.
4. Change Memory size if desired, then press Next >.
5. Select a virtual switch, then press Next >.
6. Select Use an existing virtual hard disk, then browse and select your VHD(X) file.
7. Press Finish.

[Gen2/VHDX Only] Fix Boot Options

1. Right click your virtual machine from Hyper-V Manager
2. Select Settings....
3. Select Security and under Template: select Microsoft UEFI Certificate Authority.
4. Select the SCSI Controller from the Hardware panel.
5. Select DVD Drive and press Add.

Mount the Meta-User-Data.Iso Image

1. Right click your virtual machine from Hyper-V Manager
2. Select Settings.... choose DVD Drive and press Add.
3. Select the DVD Drive. For Gen1/VHD Images, this is nested under IDE Controller 1. For Gen2/VHDX Images, this is nested under SCSI Controller.
4. Select Image File: and browse to the meta-user-data.iso file.
5. Select Apply to apply all changes.

Boot and Sign-In to your VHD

1. Right click your VM and select Connect....
2. Select Start.
3. Wait for CBL-Mariner to boot to the login prompt, then sign in with the username and password you provisioned in the meta-user-data.iso above.

ISO Image

The following builds a bootable ISO image from precompiled RPMs in the CBL-Mariner package repository at https://packages.microsoft.com/cbl-mariner/2.0/prod/.

# Switch to the toolkit folder
cd toolkit

# Image is placed in ../out/images/full
sudo make iso REBUILD_TOOLS=y REBUILD_PACKAGES=n CONFIG_FILE=./imageconfigs/full.json

Copy ISO Image to Your VM Host Machine

Copy your binary image(s) to your VM Host Machine using your preferred technique.

Create VHD(X) Virtual Machine with Hyper-V

1. From Hyper-V Select Action->New->Virtual Machine.
2. Provide a name for your VM and press Next >.
3. Select Generation 1 (VHD) or Generation 2 (VHDX), then press Next >.
4. Change Memory size if desired, then press Next >.
5. Select a virtual switch, then press Next >.
6. Select Create a virtual hard disk, choose a location for your VHD(X) and set your desired disk Size. Then press Next >.
7. Select Install an operating system from a bootable image file and browse to your CBL-Mariner ISO.
8. Press Finish.

[Gen2/VHDX Only] Fix Boot Options

1. Right click your virtual machine from Hyper-V Manager
2. Select Settings...
3. Select Security and under Template: select Microsoft UEFI Certificate Authority.
4. Select Firmware and adjust the boot order so DVD is first and Hard Drive is second.
5. Select Apply to apply all changes.

Boot ISO

1. Right click your VM and select Connect....
2. Select Start.
3. Follow the Installer Prompts to Install your image
4. When installation completes, select restart to reboot the machine. The installation ISO will be automatically ejected.
5. When prompted sign in to your CBL-Mariner using the user name and password provisioned through the Installer.