Skip to content


Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time

GitHub release CI Go Reference Go Report Card


Placemat is a tool to simulate data center networks and servers using QEMU/KVM virtual machines, and Linux networking stacks. Placemat can simulate virtually any kind of network topologies to help tests and experiments for software usually used in data centers.


  • No daemons

    Placemat is a single binary executable. It just builds networks and virtual machines when it starts, and destroys them when it terminates. This simplicity makes placemat great for a continuous testing tool.

  • Declarative YAML

    Networks, virtual machines, and other kind of resources are defined in YAML files in a declarative fashion. Users need not mind the order of creation and/or destruction of resources.

  • Virtual BMC

    Power on/off/reset of VMs can be done by IPMI commands and Redfish API. See virtual BMC for details.

  • Automation

    Placemat supports cloud-init and ignition to automate virtual machine initialization. Files on the host machine can be exported to guests as a 9pfs. QEMU disk images can be downloaded from remote HTTP servers.

    All of these help implementation of fully-automated tests.

  • UEFI

    Not only traditional BIOS, but placemat VMs can be booted in UEFI mode if OVMF is available.


This project provides these commands:

  • placemat2 is the main tool to build networks and virtual machines.
  • pmctl2 is a utility tool to control VMs and Pods.

placemat2 command

placemat2 reads all YAML files specified in command-line arguments, then creates resources defined in YAML. To destroy, just kill the process (by sending a signal or Control-C).

$ placemat2 [OPTIONS] YAML [YAML ...]

  --cache-dir string
        directory for cache data
  --data-dir string
        directory to store data (default "/var/scratch/placemat")
        show QEMU's stdout and stderr
        force run with removal of garbage
        run QEMU with graphical console
  --listen-addr string
        listen address (default "")
  --run-dir string
        run directory (default "/tmp")

If --cache-dir is not specified, the default will be /home/${SUDO_USER}/placemat_data if sudo is used for placemat. If sudo is not used, cache directory will be the same as --data-dir. --force is used for forced run. Remaining garbage, for example virtual networks, mounts, socket files will be removed.

pmctl2 command

pmctl2 is a command line tool to control VMs and Networks.

See pmctl

Getting started


For Ubuntu or Debian, you can install them as follows:

$ sudo apt-get update
$ sudo apt-get install qemu-system-x86 qemu-utils ovmf picocom socat cloud-utils

Install placemat

You can choose go get or debian package for installation.

Install placemat2 and pmctl2:

$ go install
$ go install


$ wget${VERSION}/placemat2_${VERSION}_amd64.deb
$ sudo dpkg -i placemat2_${VERSION}_amd64.deb

Run examples

See examples how to write YAML files.

To launch placemat from YAML files, run it with sudo as follows:

$ sudo $GOPATH/bin/placemat2 cluster.yml

To connect to a serial console of a VM, use pmctl2 node enter:

$ sudo $GOPATH/bin/pmctl2 node enter VM

This will launch picocom. To exit, type Ctrl-Q, then Ctrl-X.


See specifications under docs directory.


placemat is licensed under the Apache License, Version 2.0.