emu-cli: a small control toolkit for qemu
emu-cli
installs the emu
tool, which is a CLI program currently aimed at making x86 VM usage easier for Linux desktop users.
See a video of it in action: YouTube
It contains commands to:
- Manage VMs as a system-wide fleet
- List all VMs in one place, along with their run status
- Clone and Import VMs from other sources
- Create, Delete, Start, Stop, and Reboot VMs
- ISOs can be attached
- You can start VMs with or without graphical screens
emu
does not have to be running to maintain your VM
- Import and Clone VM images
- Maintain snapshots and save states
- Supervise VMs with systemd
- Uses the user profile (
systemctl --user
) - Knows about which systemd units its maintaining
- Deletes them when the VM is deleted
- Uses the user profile (
- Manage settings for VMs
- RAM, CPUs, Video & CPU type
- Forward Ports to VM networks
- Define a SSH port that stays with the VM and
emu ssh
to it easily - Poke and prod at your VMs with
emu nc
, which opens a TCP socket to the port on the VM - Play with qemu QMP commands to control your VM externally
Requirements
Linux with systemd and qemu. It places things according to the XDG standards, so that means $HOME/.local
will have the VMs, etc.
To build the software, you will need a working rust environment. I strongly recommend rustup.
Stability
emu is still undergoing some UI changes. I do use it somewhat regularly, but there may be additional work that needs to be done for a larger goal that changes small things as they stand now.
emu has bugs, particularly nasty ones at times related to your VMs. I would not use emu in a setting where data integrity mattered much.
Installation
cargo install emu-cli
Once installed, you can invoke the software with emu
.
Usage
# start the vm with the cdrom set to the ubuntu iso. Press ^C to terminate the vm.
# make a copy before doing something dumb
) ()
) ()
# supervision in systemd
) ()
) ()
# run detached and without a screen
) ()
) ()
# ssh support
# nc support
# cleanup
) ()
Configuration
Configuration is provided currently by injecting values into a file under
~/.local/share/emu/<VM>/config
. It is in TOML format.
Configuration Values
[machine]
section:
memory
: integer; memory in megabytes. Default is 16384.cpus
: integer; count of CPU cores. Default is 8.vga
: string; name of VGA driver to use withqemu -vga
. Default isvirtio
.image_interface
: string; name of interface to use for talking to images with-drive
. Defaultvirtio
is recommended.cpu_type
: string; type of CPU to support. Must be x86 and valid to pass toqemu -cpu
. Defaulthost
is recommended.ssh_port
: integer; port to contact for SSH access; used byemu ssh
. Default is 2222.
[ports]
is just a key/value map of host ports, opened on localhost
, to guest ports, opened on 0.0.0.0
. No other processing is performed.
Configuration Example
[]
= 4
= 512
[]
= 22
Management Tool
You can control these values with emu config <subcommand>
sub-commands. emu config show
, emu config set
, and emu config port
can be used to manage these sections.
The commands for emu config set
are the same as the above [machine]
section keys, only the underscores (_
) are replaced with dashes (-
); so that ssh_port
is now ssh-port
.
License
MIT
Author
Erik Hollensbe github@hollensbe.org