a small control toolkit for qemu
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
Erik Hollensbe fdaab16256 Notes on stability; update url 2 months ago
src Fix an indexing issue with the --extra parameter 6 months ago
.gitignore some stuff 7 months ago
Cargo.lock emu run -d <vm> will now detach the vm from emu, so that it can run indepedently of it. 7 months ago
Cargo.toml emu run -d <vm> will now detach the vm from emu, so that it can run indepedently of it. 7 months ago
LICENSE Licensed 7 months ago
README.md Notes on stability; update url 2 months ago


emu: a small control toolkit for qemu

emu contains commands to:

  • start and shutdown vms
  • supervise vms with userspace systemd (systemctl --user)
  • configure vm parameters & forward ports
    • by use of a INI configuration file
  • clone (stopped) vm images


The non-systemd parts probably would work on a mac with few changes. Until then this is linux-only. You will also need to be a part of your system's kvm group.


I not 100% certain what I'm trying to do with this software yet. Until then, perhaps you'll find it interesting or entertaining to play with.

emu has bugs. They don't get fixed quickly unless you fix them. I just have limited time and emu largely stays out of my way as it stands.


Install rustup to get a cargo environment, and install it from source:

cargo install --git https://github.com/erikh/emu

Once installed, you can invoke the software with emu.


$ emu create myvm 50 # gigabytes of storage
# start the vm with the cdrom set to the ubuntu iso. Press ^C to terminate the vm.
$ emu run myvm --cdrom ubuntu.iso

# make a copy before doing something dumb
$ emu clone myvm myvm.template
$ emu list

# supervision in systemd

$ emu supervise myvm
$ emu supervised
$ systemctl --user start myvm.emu # or enable it, if you'd like. it sticks to your login session.
$ systemctl --user stop myvm.emu # graceful shutdown
$ emu unsupervise myvm
$ emu remove myvm
$ emu list


Configuration is provided currently by injecting values into a file under ~/.local/share/emu/<VM>/config. It has this format (but more values, RTFS):

cpus = 4 # actually cores
memory = 512 # megabytes

2222 = 22 # host -> guest map

You can control these values with emu config <subcommand> sub-commands.

$ emu config show myvm
cpus = 4
memory = 512

2222 = 22

$ emu config port map myvm 2223 23
$ emu config port unmap myvm 2223

$ emu config set myvm cpus 8


Erik Hollensbe github@hollensbe.org