d2vm Documentation

d2vm (Docker to Virtual Machine) is a tool designed to build bootable Linux Virtual Machine (VM) images from Docker images. It is currently in alpha status.

Key Capabilities:

• Converts existing Docker images into VM images.
• Builds VM images directly from a Dockerfile.
• Generates KubeVirt Container Disk Images.

Important Constraints:

• Linux Only: Only building Linux VM images is supported.
• Distribution Discovery: The tool relies on the /etc/os-release file within the image to identify the distribution and install the appropriate Kernel. If this file is missing, the build will fail.
• Distroless Support: Distroless images are not supported because they lack the necessary metadata and tools for kernel installation.

Starting from v0.1.0, d2vm provides a fallback mechanism for environments where direct hardware/disk manipulation is restricted:

• Non-Linux Hosts (e.g., macOS): d2vm automatically runs build and convert commands inside a Docker container.
• Non-Root Users on Linux: If running without root privileges, d2vm automatically executes build and convert commands inside Docker to ensure necessary operations can proceed.

You can use d2vm to create Container Disk Images for KubeVirt.

To do this, use the --tag flag with either the build or convert commands. You can also use the --push flag to automatically push the resulting image to a registry.

Use the d2vm build command to create a VM image directly from a Dockerfile and a build context. This command accepts most flags used by docker build.

Example: Build Ubuntu VM from Dockerfile

sudo d2vm build -p MyP4Ssw0rd -f ubuntu.Dockerfile -o ubuntu.qcow2 .

Example: Build VirtualBox image

sudo d2vm build -p MyP4Ssw0rd -f ubuntu.Dockerfile -o ubuntu.vdi .

You can generate an autocompletion script for PowerShell to enable command completion for d2vm.

To load completions in your current shell session, run:

d2vm completion powershell | Out-String | Invoke-Expression

To make completions available in every new session, add the command above to your PowerShell profile.

When running a VM via the serial console, you can interact with the shell directly. To exit the terminal and stop the VM properly, use the poweroff command inside the VM:

sudo poweroff

To find the IP address of the VM for SSH connection, use:

hostname -I
# or
ip a show eth0 | grep inet | awk '{print $2}' | cut -d/ -f1

Use the d2vm run command to execute a virtual machine image. This command is the entry point for launching the VM in various environments (such as QEMU, VirtualBox, or Hetzner Cloud).

Available Options

Local Options:

• -h, --help: Display help information for the run command.

Global Options (Inherited):

• --time <string>: Enable formatted timed output. Valid formats are:
  • relative (or rel / r)
  • full (or f)
  • Default is "none".
• -v, --verbose: Enable verbose output for detailed execution logs.

d2vm run [image] [options]

Once a VM image has been built, you can run it using the qemu driver. This command starts the virtual machine with specified resource allocations.

Use the following flags:

• qemu: The driver to use.
• --mem <SIZE>: Amount of memory to allocate (e.g., 4096).
• --cpus <COUNT>: Number of CPUs to allocate.

Example run command:

d2vm run qemu --mem 4096 --cpus 4 workstation.qcow2

d2vm run qemu --mem 4096 --cpus 4 $IMAGE

You can generate a bash autocompletion script for the d2vm CLI to improve your shell experience. This script requires the bash-completion package to be installed on your system via your OS package manager.

Load completions for the current session

To immediately enable autocompletion in your active terminal session, run:

source <(d2vm completion bash)

Load completions permanently

To ensure autocompletion is available in every new shell session, write the output to your system's completion directory. Note that you must start a new shell for these changes to take effect.

On Linux:

d2vm completion bash > /etc/bash_completion.d/d2vm

On macOS:

d2vm completion bash > $(brew --prefix)/etc/bash_completion.d/d2vm

The d2vm program supports shell completion for bash, zsh, and fish. To enable it for your current session, run:

source <(d2vm completion $(basename $SHELL))

To view help for installing completion files in your shell's completion directory, use:

d2vm completion $(basename $SHELL) --help

You can generate autocompletion scripts for the d2vm CLI to enable tab-completion in your terminal. The completion command produces the script required for your specific shell (bash, fish, powershell, or zsh).

To use the generated script, refer to the specific documentation for your shell (e.g., d2vm_completion_bash.md) for instructions on how to source or install the output into your shell configuration.

d2vm completion [options]