Installation Guide

This guide installs OpenVMX. It covers four tasks: build a bootable image from source, boot it under QEMU, install a product kit onto a system disk with PRODUCT INSTALL, and log in to the disk you installed. Every command is one you can run. The install commands are the ones a continuous-integration gate runs on every change: it boots OpenVMX, types these commands, and checks that the files land on the target volume.

1Before you begin

1.1What this guide installs

OpenVMX reimplements a VMS operating environment: the DCL command language, Record Management Services, the system services, and a kernel-resident executive (vms.ko) that userspace reaches through /dev/vms. It runs as a QEMU virtual machine.

This guide follows the install path the current release runs. You build a bootable image, boot it, and use PRODUCT INSTALL to write a product kit onto a target volume. The install lays the volume out as a rooted system disk, under [SYS0.SYSCOMMON]. You then boot that disk on its own and log in. The result is a system disk that holds an OpenVMX system tree and a product database, and that boots to a login prompt without any further step.

1.2What you need

• A host that runs Linux containers, with Docker or Podman. The build runs the whole toolchain inside the container. You do not install a compiler, kernel headers, or QEMU on the host.
• An x86-64 or aarch64 host. The build and the boot commands select the matching QEMU (qemu-system-x86_64 or qemu-system-aarch64).
• A few gigabytes of free disk, and about ten minutes for the first build. Later builds reuse the cache.

1.3The accounts you use

Two accounts authenticate on a stock system. Use SYSTEM for the install. Every other account in the user authorization file ships with no password and is refused at login.

2Building the bootable image

The build runs in a container and produces a tagged image named ovmx-boot. That image carries the kernel, the bootstrap, a distribution system disk, and the product kit.

2.1Get the source

# clone the source
$ git clone https://github.com/3dl-dev/vms.git
$ cd vms

2.2Build the image

Build with plain docker build -t. This needs no build plugins and works on a stock Docker install.

# build the bootable image; all build tools run in the container
$ docker build -f distro/Dockerfile.bootable -t ovmx-boot .

The build compiles the kernel modules, the userland, and the system-image graph, then packs the boot artifacts. On a cold build this takes about ten minutes. When it finishes, docker images ovmx-boot shows the tagged image.

2.3What the build produces

The ovmx-boot image carries the pieces you boot. They sit under /boot inside the image.

3Booting the system

Boot the distribution disk first, to confirm the image works before you install. The image runs OpenVMX under QEMU. It selects the QEMU binary for the host architecture.

3.1Boot the distribution disk

Run the image with DISTRIB set. On first run it copies the distribution disk into place and boots it. Mount a host directory at /data to keep the disk between runs.

# boot the distribution disk under QEMU
$ docker run --rm -it -e DISTRIB=1 -v "$PWD/dist:/data" ovmx-boot

3.2Reach the login prompt

The console shows the kernel and startup messages, then stops. Press RETURN. The operator terminal waits for it before it prompts. The system displays:

Username: SYSTEM
Password: MANAGER

    Welcome to OpenVMX
$

The password is not echoed. After a correct login the system displays its banner and the DCL prompt, $. To leave QEMU, press Ctrl-A then X.

3.3Conversational boot

To stop before the executive attaches and inspect the boot parameters, set BOOT_FLAGS to 0,1. Bit 0 of the second value is the conversational bit.

$ docker run --rm -it -e DISTRIB=1 -e BOOT_FLAGS=0,1 -v "$PWD/dist:/data" ovmx-boot

The boot halts at the SYSBOOT> prompt. There you can SHOW and SET parameters. Type CONTINUE to resume the boot.

4Installing to a system disk

You now install the product kit onto a separate target volume. The install writes a rooted system tree and a product database onto that volume. The install commands in this chapter (MOUNT, PRODUCT INSTALL, PRODUCT SHOW PRODUCT, DISMOUNT) are the ones the gate tests/qemu/test_product_install_e2e.sh types on every change; a release cut and every documentation change re-check this manual against that gate, command for command.

4.1Prepare a target volume

The target must be a formatted volume before you mount it. Build the volume tool with the local tools target, create a blank disk file, and format it. The tool build needs a C compiler and CMake on the host; see Appendix A.

# build INITIALIZE.EXE, the volume tool
$ cmake -B build -DBUILD_TOOLS=ON
$ cmake --build build -j$(nproc)

# create a blank 64 MB disk and format it as a volume labelled WORK
$ truncate -s 64M target.img
$ build/bin/INITIALIZE.EXE target.img WORK 64

4.2Boot with the target attached

Boot the distribution disk with the target attached as a second virtio disk. Inside the running system the target appears as VDA100:. Bind-mount the current directory so the install writes to target.img on the host.

$ docker run --rm -it -v "$PWD:/work" --entrypoint qemu-system-x86_64 ovmx-boot \
    -kernel /boot/vmlinuz -initrd /boot/initramfs-ovmx.cpio.gz \
    -nographic -append "console=ttyS0 loglevel=3 quiet" \
    -m 512M -smp 1 -nic none -nodefaults -serial mon:stdio \
    -drive file=/boot/ovmx-distrib.img,format=raw,if=virtio \
    -drive file=/work/target.img,format=raw,if=virtio \
    -no-reboot

Log in as SYSTEM, as in Chapter 3. The next four commands run at the DCL prompt.

4.3Mount the target volume

Type MOUNT with the device and its label. The system mounts the volume through the executive and confirms it.

$ MOUNT VDA100: WORK
%MOUNT-I-MOUNTED, WORK mounted on _VDA100:

4.4Install the kit

Type PRODUCT INSTALL, naming the kit at SYS$UPDATE: and the destination device. The install reads the kit and writes the system tree onto VDA100:.

$ PRODUCT INSTALL VMS /SOURCE=SYS$UPDATE:OVMX-OS.KIT /DESTINATION=VDA100:
%PCSI-I-DONE

A %PCSI-I-DONE line with no %PCSI-E- or %PCSI-F- line means the files landed.

4.5Confirm the files and dismount

List a file the install wrote, to confirm the rooted layout. Then read the product database on the target, and dismount to flush the volume.

$ DIRECTORY VDA100:[SYS0.SYSCOMMON.SYSEXE]DCL.EXE
Directory VDA100:[SYS0.SYSCOMMON.SYSEXE]
DCL.EXE;1
Total of 1 file.

$ PRODUCT SHOW PRODUCT /DESTINATION=VDA100:
PRODUCT                          KIT TYPE      STATE
X86VMS VMS                       Full LP       Installed

$ DISMOUNT VDA100:
%DISMOUNT-I-DISMOUNTED, WORK dismounted from _VDA100:

The product name comes from the kit. On an x86-64 build the kit is named X86VMS VMS. Shut the machine down with Ctrl-A then X.

5First boot and login

5.1Boot the installed disk

Boot the installed target on its own, as the only system disk, with the bootstrap. Because the bootstrap carries no DCL and no system libraries, reaching a login prompt proves the install wrote a working system onto the disk.

$ docker run --rm -it -v "$PWD:/work" --entrypoint qemu-system-x86_64 ovmx-boot \
    -kernel /boot/vmlinuz -initrd /boot/initramfs-ovmx.cpio.gz \
    -nographic -append "console=ttyS0 loglevel=3 quiet" \
    -m 512M -smp 1 -nic none -nodefaults -serial mon:stdio \
    -drive file=/work/target.img,format=raw,if=virtio \
    -no-reboot

The disk mounts as DKA0:, the system disk, and startup runs. If the console shows %OVMX-F-SYSINIT and stops, the installed layout is not bootable; see Appendix B.

5.2Log in

Press RETURN at Username:. Log in as SYSTEM with the password MANAGER. The system reaches the DCL prompt. DCL activated from the installed disk, since the bootstrap does not carry it.

6Verifying the installation

Run these commands at the DCL prompt on the booted system. Each one reads from the installed disk.

6.1Confirm DCL is running

Type SHOW TIME. The system displays the current date and time. This confirms DCL activated from the installed disk.

$ SHOW TIME
  13-AUG-2026 09:14:07

6.2Check the system tree and product database

List the DCL image through the SYS$SYSTEM: logical name, which resolves into the rooted tree on the booted disk. Then list the installed product.

$ DIRECTORY SYS$SYSTEM:DCL.EXE
Directory SYS$COMMON:[SYSEXE]
DCL.EXE;1
Total of 1 file.

$ PRODUCT SHOW PRODUCT
PRODUCT                          KIT TYPE      STATE
X86VMS VMS                       Full LP       Installed

6.3List the system

Type SHOW SYSTEM. The system lists its processes. Table 6–1 lists other commands that read installed state.

AAppendix A. Build prerequisites

• Docker or Podman. The bootable image build (Chapter 2) runs entirely in the container.
• CMake, a C compiler, and make. The volume tool in Section 4.1 (INITIALIZE.EXE) builds on the host with cmake -B build -DBUILD_TOOLS=ON.
• An x86-64 or aarch64 host.

On an aarch64 host, the direct QEMU commands in Chapters 4 and 5 change in three values. Use qemu-system-aarch64 for the entrypoint, add -machine virt -cpu cortex-a57, and set the console to console=ttyAMA0 in the -append string. The rest of each command is the same.

BAppendix B. Troubleshooting

CAppendix C. Not yet available

OpenVMX is under development. These parts of a VMS install are not implemented in V0.6. This guide does not use them.

• A menu-driven install from boot media. The numbered install menu is not wired for an end-to-end install. Install runs from a logged-in session with PRODUCT INSTALL, as in Chapter 4.
• A first-boot configuration pass. There is no separate reconfiguration boot: no parameter-feedback pass, no page or swap file sizing, and no security, audit, or ACME server bring-up. The install produces a directly bootable disk.
• Networking as a VMS device. TCP/IP Services ships as a layered product in V0.6 (configuration plane, TCPIP$ logicals, PING, the NIC as ETH0:) — see the TCP/IP Configuration Guide. DECnet Phase IV routing, NSP transport, the node database, and outbound SET HOST ship as well. The install itself does not configure networking; see the compatibility surface for what each protocol supports today.
• Cluster membership. V0.6 makes OpenVMX a cluster participant (distributed lock manager over the interconnect, membership in the executive, SHOW CLUSTER). Standing up and configuring a cluster is described in Cluster Systems. Quorum/votes and MSCP-served volumes are not yet enforced.

For the current status of every facility, see the compatibility surface.