io7m | single-page | multi-page
Waxmill User Manual 0.0.2
Previous
Waxmill User Manual 0.0.2
Up
2. Usage
Next
1

# Orientation

- 1. Orientation
  - 1.1. Overview
    - 1.1.1. Design Principles
    - 1.1.2. Plain Text Configuration
    - 1.1.3. Memory Safety, Type Safety
    - 1.1.4. Process Supervision

1.1

## Overview

1.1.1

## Design Principles

1
The Waxmill package provides a command-line interface and Java API for creating, configuring, and running bhyve virtual machines. The package follows a number of design principles in order to ensure stability and reliability.
1.1.2

## Plain Text Configuration

1
The Waxmill package stores configuration data for virtual machines in a strict, strongly-typed, versioned XML format. This ensures that virtual machine configurations created by older versions of the Waxmill package can continue to be understood by newer versions of Waxmill, or can be safely migrated to newer formats without any loss of information. Waxmill unconditionally validates all input against a schema (including data that the package wrote itself), and will refuse to work with malformed and/or invalid data. Additionally, the Waxmill package uses a hardened XML parser configuration that is expected to be immune to entity expansion attacks.
1.1.3

## Memory Safety, Type Safety

1
The Waxmill package is written in Java 11, using only a couple of native methods (fork() and execve()), and is therefore likely to be immune to buffer overflows and other memory-safety related bugs that plague the typical present-day system languages. The codebase is, additionally, subjected to extensive static checking on every build. Binary builds are expected to be byte-for-byte reproducible. Extensive use of static typing is used throughout the codebase to enforce invariants statically where possible, and the code is annotated with precondition/invariant/postcondition checks in order to induce bugs to cause early failures instead of silently corrupting state. The codebase also has a high-coverage test suite which exhaustively tests the various API methods and the entire command-line interface.
1.1.4

## Process Supervision

1
The Waxmill package is designed to work under process supervision. The supervision of system services has been a solved problem for decades although many pieces of server software are still not designed to work well under process supervision. Many virtual machine management systems still work with incredibly fragile rc-style scripts and pidfiles that instantly become stale and dangerous on virtual machine crashes. The Waxmill package provides a single command to start a virtual machine in the foreground such that the virtual machine can be supervised using systems such as daemontools, or runit. These tools can guarantee that a virtual machine always starts from a clean slate, and will always be reliably restarted should it crash.
Waxmill User Manual 0.0.2
Previous
Waxmill User Manual 0.0.2
Up
2. Usage
Next
io7m | single-page | multi-page