minimega 2.0 release notes¶
Introduction¶
The minimega development team is pleased to announce the release of minimega 2.0. This release is marked by sweeping changes to the command line infrastructure, documentation, compatibility, and several new features.
What's new¶
Major changes and milestones¶
Transition to github.com¶
minimega is now hosted on github. This came both as a response to Google announcing the end of code.google.com, as well as to incorporate key features available at github, including better code review and ssh git access.
minimega.org¶
minimega once again has a website at minimega.org which also serves installation, usage, and API documentation. minimega.org reflects the current release. To view documentation rendered from the head of the repository, see tip.minimega.org.
Documentation¶
A big push to document all tools and features of the minimega distribution is
underway, and a large chunk of that effort is complete and hosted on the
website. Documents can be written as articles or slidedecks, and are rendered
by the documentation tool minidoc. API documentation is now automatically
generated at compile time, and include the entire API help text you will find
on the command line.
minicli¶
The most salient change in minimega 2.0 is minicli, which represents an
attempt to unify the command line interface, API style, error reporting, and
data management. As part of this change, many of the old commands have been
updated, which will require updating any minimega scripts you use. One of the
primary goals of these CLI changes was to provide a consistent "feel" across
all the commands.
A major addition to the CLI is the addition of built-in commands that can
mutate the output from other commands. For example, .filter can be used to
select particular rows from a response and .columns can be used to select
particular columns. These built-ins can be stacked to select a small subset of
the results from a command, for example:
There are also built-ins that change how the result of a command is displayed.
.annotate controls whether the hostname of the machine that ran the command
is included. .compress controls whether identical responses from multiple
hosts are compressed into a single response with a range-style hostname
annotation. .json and .csv can be used to change the output to JSON or
CSV-formatted text. Consult help for a full list of the built-in commands and
their uses.
New web interface¶
The web interface has been completely rebuilt for minimega 2.0. In addition to
listing the running VMs and supporting VNC connections, as was supported by the
old web interface, web 2.0 can display information about hosts connected to the
mesh, show tiles of screenshots from all running VMs, and plot all running VMs
on a map with the appropriate tags set via vm tags.
cc virtio-serial support¶
The command and control API, used to drive runtime applications on launched on endpoints, now supports both TCP and virtio-serial connections. virtio-serial connections are supported on both Linux and Windows endpoints. The use of virtio-serial for cc connections allows networkless backchannels for command and control.
See the cc API documentation for more information.
cc tunnelling¶
The cc API now supports TCP tunnelling over the cc transport layer, including over virtio. cc tunnelling is equivalent to SSH tunnelling (-L flag in ssh), and supports both forward and reverse tunnels. This means you can create TCP tunnels over otherwise no-net VMs for networkless backchannel access.
See the cc API documentation for more information.
Additional new features¶
Bandwidth stats¶
The host API already reports bandwidth statistics on all bridges owned by
minimega. Now it reports split rx/tx statistics as an aggregate of all
interfaces minimega owns (taps). This reporting is more accurate as it doesn't
include bandwidth used by access ports on a given bridge.
Additionally, per interface bandwidth is now reported in the vm info API.
Bridge trunk¶
The ability to add trunk ports to an openvswitch bridge directly from minimega
has been added to the bridge API. See the
bridge API for more information.
Command line pager¶
Some minimega commands can return a lot of output to the terminal, especially when minimega is distributed across a small cluster. When minimega is being run interactively, it will automatically page the output from commands to the user's terminal height.
Debian release packaging¶
A script is now provided to build a Debian package from the
repository. It will compile all components of the minimega ecosystem,
then create a .deb file. This package will install the full minimega
environment into /opt/minimega and place licensing information into
the standard /usr/share/doc/minimega location.
To build:
Deploy api¶
For simple cluster environments, the new deploy API supports copying and
launching minimega from a single node, further simplifying the installation and
use of minimega. The deploy API uses scp to copy itself to a specified list
of nodes (using the same range notation used in the mesh send API), and
launches minimega using the same command line arguments used to launch the
running instance.
See the deploy API for more information.
New python bindings¶
It is now possible to automatically generate the python bindings for whichever
version of minimega you are using. The bindings generated are a 1:1 wrapper
around the CLI, and should work for both python2 and python3. See the
documentation in misc/python/genapi.py for instructions on building the
minimega.py api file.
VNC¶
minimega 2.0 includes an RFB encoder/decoder with limited support for reading
framebuffer updates. This enables minimega 2.0 to do two things. First, it
allows minimega to write the keyboard and mouse recordings in a human-readable
format. In the previous version of minimega, the keyboard and mouse recordings
for VNC sessions were stored as raw bytes from the RFB protocol. This means
that after a recording is finished, you may edit the recording or cut and paste
multiple recordings before playback. Second, the more complete protocol support
should ensure that framebuffer recording (and playback with rfbplay) works
consistently.
protonuke json email file¶
protonuke now supports sending email attachments when using an optional external email corpus. A single file or directory may be specified. If a directory is specified, a random file from that directory will be used when generating email.
See the SMTP section of the protonuke guide for more information.
Recursive file api¶
The file API now supports recursively tranferring entire directories to
remote nodes. To transfer a directory, simply specify the directory to transfer
with file get as usual. Additionally, the file API now allows only 3
in-flight transfers at a time, queuing additional transfer requests.
See the file API for more information.
vm migrate / vm config migrate¶
The vm migrate API allows saving the state of a running or paused VM to disk.
This file is appropriate for reloading a VM later or on another node in exactly
the same state as when it was saved. The vm config migrate API allows
launching VMs from a saved state by specifying the migration file. It's
especially useful to use vm migrate in conjunction with vm save to create a
saved VM for later reuse.
See the vm migrate and vm config migrate API for more information.
vm screenshot¶
The vm screenshot API allows taking screenshots of a running VM's framebuffer
in the PNG format. Images are saved to the VM's runtime directory (by default
/tmp/minimega/<vm id>/screenshot.png).
See the screenshot API for more information.
vm tag¶
VMs now support tags that allow the user to set and get arbitrary key/values pairs for VMs. This is currently used by the new web interface to plot VMs that have the lat/long tags on a map. We hope that other third-party apps may make use of the tags to add interesting new features.
See the vm tag API for more information.
vmbetter iso generation¶
The vmbetter tool can now generate bootable ISO images. Simply specify
the -iso flag to enable.
Changes from previous versions¶
cc api rewrite¶
The cc API has been rewritten to better reflect the rest of the minimega API
style. Commands are now one-liners, such as cc send foo, which will send a
file foo. The other command and control semantics, such as in-order
processing of commands, are still valid.
See the cc API for more information.
IP learning now bridge specific¶
minimega snoops ARP and neighbor discovery traffic on local VMs in order to
associate IP addresses at runtime with VMs, as reflected in vm info. In
previous versions, minimega simply inspected all bridges for this information.
This was problematic if VMs with identical MAC addresses existed on different
bridges. Snooping is now bridge-specific, and identical MAC addresses (on
different bridges) now behave correctly.
vm cdrom eject/change¶
The vm cdrom commands allow the user to change the CDROM image in
use by a running VM.
See the vm cdrom API documentation for more information.
Availability¶
minimega is available in several ways, both as pre-built distributions and source. See the installing guide for more information.
Debian package¶
minimega is available as an x86-64 debian package, available here. It is known to work in debian 7 (wheezy) and 8 (testing/jessie).
tarball¶
A pre-built, x86-64 distribution is available in a single distributable tarball
here. It should be sufficient to simply unpack the tarball and run tools
from the bin/ directory directly. Most default paths in minimega, vmbetter,
and other tools are built to be used in this way (i.e. bin/minimega, which
will then look for the web directory in misc/web).
Building from source¶
Source of the entire distribution is available on github. Follow the directions for cloning or forking minimega on github.com. In order to build minimega, you will need a Go 1.3+ compiler, libreadline, and libpcap headers.