Navigation

Introduction Builtins .alias .annotate .columns .compress .csv .env .filter .headers .json .preprocess .record .sort .unalias Mesh Commands mesh degree mesh dial mesh dot mesh hangup mesh list mesh send mesh status mesh timeout VM Commands clear vm config clear vm config tag clear vm net bond clear vm tag vm vm cdrom vm config vm config append vm config backchannel vm config cdrom vm config colocate vm config cores vm config coschedule vm config cpu vm config disks vm config fifos vm config filesystem vm config hostname vm config init vm config initrd vm config kernel vm config machine vm config memory vm config migrate vm config networks vm config preinit vm config qemu vm config qemu-append vm config qemu-override vm config schedule vm config serial-ports vm config snapshot vm config sockets vm config tags vm config threads vm config uuid vm config vcpus vm config vga vm config virtio-ports vm config volume vm hotplug vm info vm launch vm migrate vm net vm qmp vm screenshot vm snapshot vm tag vm top Host and Other Commands host background bridge capture cc cc mount check clear all clear capture clear cc clear cc mount clear deploy flags clear history clear log clear namespace clear optimize clear pipe clear plumb clear qos clear router clear tap clear vlans clear vnc debug deploy disk dnsmasq dnsmasq configure echo file help history log file log filter log level log mesh log ring log stderr log syslog namespace ns nuke optimize pipe plumb qos quit read router shell status updates tap version viz vlans vnc write

minimega API

Auto-generated by apigen
Last updated 24 January 2023

Introduction

This document contains an automatically generated form of the minimega command
API help text. The same help text (minus some examples included here) is
available in minimega by using the `help` command. You can get specific help on
a minimega command by using `help`<command>`.

Builtins

Builtins are commands that impact how responses to commands are rendered. Some
builtins impact how data is displayed, such as `.csv` and `.json`, while other
impact what data is displayed, such as `.columns`. All builtins are stackable,
meaning you can issue one-line commands by suffixing a builtin with a command
or another builtin.

.alias

.alias
.alias <alias>...

Create a new alias similar to bash aliases. Aliases can be used as a shortcut
to avoid typing out a long command. Only one alias is applied per command and
only to the beginning of a command. For example:

.alias vmr=.filter state=running vm info

The alias is interpreted as the text up to the first "=". Runing .alias without
any argument will list the existing aliases.

This alias allows the user to type "vmr" rather than the using a filter to list
the running VMs.

.unalias removes a previously set alias.

Note: we *strongly* recommend that you avoid aliases, unless you are using the
shell interactively. Aliases save typing which should not be necessary if you
are writing a script.

.annotate

.annotate [true,false]
.annotate <true,false> (command)

Enable or disable hostname annotation for responses.

.columns

.columns <columns as csv> (command)

Filter tabular data using particular column names. For example, to display
only the vm name and state:

.columns name,state vm info

Column names are comma-seperated. .columns can be used in conjunction with
.filter to slice a subset of the rows and columns from a command, however,
these commands are not always interchangeable. For example, the following is
acceptable:

.columns name,state .filter vcpus=4 vm info

While the following is not:

.filter vcpus=4 .columns name,state vm info

This is because .columns strips all columns except for name and state from the
tabular data.

Note: the annotate flag controls the presence of the host column.

.compress

.compress [true,false]
.compress <true,false> (command)

Enable or disable output compression of like output from multiple responses.
For example, if you executed a command using mesh, such as:

mesh send node[0-9] version

You would expect to get the same minimega version for all 10 nodes. Rather than
print out the same version 10 times, minicli with compression enabled would print:

node[0-9]: minimega <version>

Assuming that all the minimega instances are running the same version. If one node was running
a different version or has an error, compression is still useful:

node[0-4,6-9]: minimega <version>
node5: minimega <version>

Or,

node[0-3,9]: minimega <version>
node[4-8]: Error: <error>

Compression is not applied when the output mode is JSON.

.csv

.csv [true,false]
.csv <true,false> (command)

Enable or disable CSV mode. Enabling CSV mode disables JSON mode, if enabled.

.env

.env [name]
.env <name> <value>

Print or update env variables. To unset an env variables, use:

.env <name> ""

.filter

.filter <filter> (command)

Filters tabular data based on the value in a particular column. For example, to
search for vms in a particular state:

.filter state=running vm info

Filters can also be inverted:

.filter state!=running vm info

Filters are case insensitive and may be stacked:

.filter state=RUNNING .filter vcpus=4 vm info

If the column value is a list or an object (i.e. "[...]", "{...}"), then
.filter implicitly uses substring matching.

Substring matching can be specified explicity:

.filter state~run vm info
.filter state!~run vm info

.headers

.headers [true,false]
.headers <true,false> (command)

Enable or disable headers for tabular data.

.json

.json [true,false]
.json <true,false> (command)

Enable or disable JSON mode. Enabling JSON mode disables CSV mode, if enabled.

.preprocess

.preprocess [true,false]
.preprocess <true,false> (command)

Enable or disable the command preprocessor.

.record

.record [true,false]
.record <true,false> (command)

Enable or disable the recording of a given command in the command history.

.sort

.sort [true,false]
.sort <true,false> (command)

Enable or disable sorting of tabular data based on the value in the first
column. Sorting is based on string comparison.

.unalias

.unalias <alias>

Removes an alias by name. See .alias for a listing of aliases.

Mesh Commands

Mesh commands control the behavior and operation of communication between
minimega nodes on a network. minimega is fully distributed, and commands to
other minimega nodes can be issued from any other participating minimega node.
For example, you can get the hostname of all minimega nodes (exclusive of the
issuing node) with `mesh`send`all`host`name`.

Generally, `mesh`send` will be the only mesh command you will use. The other
commands provided are for manually dialing other nodes and controlling network
behavior.

mesh degree

mesh degree [degree]

mesh dial

mesh dial <hostname>

mesh dot

mesh dot <filename>

Output a graphviz formatted dot file representing the connected topology.

mesh hangup

mesh hangup <hostname>

mesh list

mesh list [all,peers]

Without "all" or "peers", displays the mesh adjacency list. If "all" is
specified, the hostnames of all nodes in the list are printed. If "peers" is
specified, the hostnames of all peers are printed (the local node is not
included).

mesh send

mesh send <hostname or range or all> (command)

Send a command to one or more connected clients. For example, to get the
vm info from nodes kn1 and kn2:

mesh send kn[1-2] vm info

You can use 'all' to send a command to all connected clients.

mesh status

mesh status

mesh timeout

mesh timeout [timeout]

View or set the timeout on sending mesh commands.

When a mesh command is issued, if a response isn't sent within mesh timeout
seconds, the command will be dropped and any future response will be discarded.


response.

By default, the mesh timeout is 0 which disables timeouts.

VM Commands

VM commands control the state, monitoring, and launching of VMs on a minimega
node. VMs are launched by describing the VM parameters with the various
`vm`config` commands. One the VM is described, one or more instances of that
description may be launched. The VM description can be modified for subsequent
VMs.

clear vm config

clear vm config
clear vm config <append,>
clear vm config <backchannel,>
clear vm config <cpu,>
clear vm config <cdrom,>
clear vm config <colocate,>
clear vm config <cores,>
clear vm config <coschedule,>
clear vm config <disks,>
clear vm config <fifos,>
clear vm config <filesystem,>
clear vm config <hostname,>
clear vm config <init,>
clear vm config <initrd,>
clear vm config <kernel,>
clear vm config <machine,>
clear vm config <memory,>
clear vm config <migrate,>
clear vm config <networks,>
clear vm config <preinit,>
clear vm config <qemu-append,>
clear vm config <qemu-override,>
clear vm config <qemu,>
clear vm config <schedule,>
clear vm config <serial-ports,>
clear vm config <snapshot,>
clear vm config <sockets,>
clear vm config <tags,>
clear vm config <threads,>
clear vm config <uuid,>
clear vm config <vcpus,>
clear vm config <vga,>
clear vm config <virtio-ports,>
clear vm config <volume,>

clear vm config tag

clear vm config tag <key>

Remove tags in the same manner as "clear vm tag".

clear vm net bond

clear vm net bond <vm target> [name]

clear vm tag

clear vm tag
clear vm tag <vm target> [tag]

Clears one, many, or all tags from a virtual machine.

Clear the tag "foo" from VM 0:

clear vm tag 0 foo

Clear the tag "foo" from all VMs:

clear vm tag all foo

Clear all tags from VM 0:

clear vm tag 0

Clear all tags from all VMs:

clear vm tag all

vm

vm <kill,> <vm target>
vm <stop,> <vm target>
vm <flush,>
vm <flush,> <vm target>
vm <start,> <vm target>

Kill one or more running virtual machines. See "vm start" for a full
description of allowable targets.
Stop one or more running virtual machines. See "vm start" for a full
description of allowable targets.

Calling stop will put VMs in a paused state. Use "vm start" to restart them.
Flush one or more virtual machines. Discard information about VMs that
have either quit or encountered an error. This will remove VMs with a state of
"quit" or "error" from vm info. Names of VMs that have been flushed may be
reused.

Note running without arguments results in the same behavior as using the "all"
target. See "vm start" for a full description of allowable targets.
Start one or more paused virtual machines. VMs may be selected by name, range, or
wildcard. For example,

To start vm foo:

vm start foo

To start vms foo and bar:

vm start foo,bar

To start vms foo0, foo1, foo2, and foo5:

vm start foo[0-2,5]

There is also a wildcard (all) which allows the user to specify all VMs:

vm start all

Note that including the wildcard in a list of VMs results in the wildcard
behavior (although a message will be logged).

Calling "vm start" on a specific list of VMs will cause them to be started if
they are in the building, paused, quit, or error states. When used with the
wildcard, only vms in the building or paused state will be started.

vm cdrom

vm cdrom <eject,> <vm target> [force,]
vm cdrom <change,> <vm target> <path> [force,]

Eject or change an active VM's cdrom image.

Eject VM 0's cdrom:

vm cdrom eject 0

Eject all VM cdroms:

vm cdrom eject all

If the cdrom is "locked" by the guest, the force option can be used to override
the lock:

vm cdrom eject 0 force

Change a VM to use a new ISO:

vm cdrom change 0 /tmp/debian.iso

"vm cdrom change" ejects the current ISO, if there is one.

See "vm start" for a full description of allowable targets.

vm config

vm config
vm config <save,> <name>
vm config <restore,> [name]
vm config <clone,> <vm name>

Display, save, or restore the current VM configuration. Note that saving and
restoring configuration applies to all VM configurations including KVM-based VM
configurations.

To display the current configuration, call vm config with no arguments.

List the current saved configurations with 'vm config restore'.

To save a configuration:

vm config save <config name>

To restore a configuration:

vm config restore <config name>

To clone the configuration of an existing VM:

vm config clone <vm name>

Clone reparses the original network "vm config net". If the cloned VM was
configured with a static MAC, the VM config will not be launchable. Clone also
clears the UUID.

Calling clear vm config will clear all VM configuration options, but will not
remove saved configurations.

vm config append

vm config append [value]...

Add an append string to a kernel set with vm kernel. Setting vm append
without using vm kernel will result in an error.

For example, to set a static IP for a linux VM:

vm config append ip=10.0.0.5 gateway=10.0.0.1 netmask=255.255.255.0 dns=10.10.10.10

Note: this configuration only applies to KVM-based VMs.

vm config backchannel

vm config backchannel [true,false]

Enable/disable serial command and control layer for this VM.

Default: true

vm config cdrom

vm config cdrom [value]

Attach a cdrom to a VM. When using a cdrom, it will automatically be set
to be the boot device.

Note: this configuration only applies to KVM-based VMs.

vm config colocate

vm config colocate [value]

Colocate this VM with another VM that has already been launched or is
queued for launching.

Note: Cannot specify Colocate and Schedule in the same

vm config cores

vm config cores [value]

Set the number of CPU cores per socket. If unspecified, QEMU will
calculate missing values based on vCPUs, sockets, and threads.

vm config coschedule

vm config coschedule [value]

Set a limit on the number of VMs that should be scheduled on the same
host as the VM. A limit of zero means that the VM should be scheduled by
itself. A limit of -1 means that there is no limit. This is only used
when launching VMs in a namespace.

Default: -1

vm config cpu

vm config cpu [value]

Set the virtual CPU architecture.

By default, set to 'host' which matches the host CPU. See 'qemu -cpu
help' for a list of supported CPUs.

The accepted values for this configuration depend on the QEMU binary
name specified by 'vm config qemu'.

Note: this configuration only applies to KVM-based VMs.

Default: "host"

vm config disks

vm config disks [diskspec]...

Specify one or more disks to be connected to a VM. Any disk image supported by QEMU is a valid parameter.

Optionally, you may specify the drive interface for QEMU to use. By default,
"ide" is used. Supported interfaces are "ahci", "ide", "scsi", "sd", "mtd",
"floppy", "pflash", and "virtio".

Optionally, you may specify the cache mode to be used by the drive. By default,
"unsafe" is used for vms launched in snapshot mode, and "writeback" is used
otherwise. Supported cache modes are "none", "writeback", "unsafe",
"directsync", and "writethrough".

Note: although disk snapshot image files are saved in the temporary vm instance
paths, they may not be usable if the "unsafe" cache mode is used, as all flush
commands from the guest are ignored in that cache mode. For example, even if
you shut down the guest cleanly, there may still be data not yet written to the
snapshot image file. If you wish to copy and use the snapshot image file
cleanly, you can flush the disk cache manually via the QMP command socket, or
specify a different cache mode such as "writeback".

The order is:

<path>,<interface>,<cache mode>

Examples:

To attach a disk with the default interface and cache mode:

vm config disk linux_disk.qcow2

To attach 2 disks using the "ide" interface for the first disk and default
interface for the second disk:

vm config disk linux_disk.qcow2,ide storage_disk.qcow2

To attach a disk using the "ide" interface with the "unsafe" cache mode:

vm config disk linux_disk.qcow2,ide,unsafe

Disk images launched in snapshot mode may safely be used for multiple VMs.

Calling vm config disks with no arguments prints the current configuration.

Note: this configuration only applies to KVM-based VMs.

vm config fifos

vm config fifos [value]

Set the number of named pipes to include in the container for
container-host communication. Named pipes will appear on the host in the
instance directory for the container as fifoN, and on the container as
/dev/fifos/fifoN.

Fifos are created using mkfifo() and have all of the same usage
constraints.

Note: this configuration only applies to containers.

vm config filesystem

vm config filesystem [value]

Configure the filesystem to use for launching a container. This should
be a root filesystem for a linux distribution (containing /dev, /proc,
/sys, etc.)

Note: this configuration only applies to containers and must be specified.

vm config hostname

vm config hostname [value]

Set a hostname for a container before launching the init program. If not
set, the hostname will be the VM name. The hostname can also be set by
the init program or other root process in the container.

Note: this configuration only applies to containers.

vm config init

vm config init [value]...

Set the init program and args to exec into upon container launch. This
will be PID 1 in the container.

Note: this configuration only applies to containers.

Default: "/init"

vm config initrd

vm config initrd [value]

Attach an initrd image to a VM. Passed along with the kernel image at
boot time.

Note: this configuration only applies to KVM-based VMs.

vm config kernel

vm config kernel [value]

Attach a kernel image to a VM. If set, QEMU will boot from this image
instead of any disk image.

Note: this configuration only applies to KVM-based VMs.

vm config machine

vm config machine [value]

Specify the machine type. See 'qemu -M help' for a list supported
machine types.

The accepted values for this configuration depend on the QEMU binary
name specified by 'vm config qemu'.

Note: this configuration only applies to KVM-based VMs.

vm config memory

vm config memory [value]

Configures the amount of physical memory to allocate (in megabytes).

Default: 2048

vm config migrate

vm config migrate [value]

Assign a migration image, generated by a previously saved VM to boot
with. By default, images are read from the files directory as specified
with -filepath. This can be overriden by using an absolute path.
Migration images should be booted with a kernel/initrd, disk, or cdrom.
Use 'vm migrate' to generate migration images from running VMs.

Note: this configuration only applies to KVM-based VMs.

vm config networks

vm config networks [netspec]...

Specify the network(s) that the VM is a member of by VLAN. A corresponding VLAN
will be created for each network. Optionally, you may specify the bridge the
interface will be connected on. If the bridge name is omitted, minimega will
use the default "mega_bridge".

You can also optionally specify the MAC address of the interface to connect to
that network. If not specifed, the MAC address will be randomly generated.

You can also optionally specify a network device for qemu to use (which is
ignored by containers). By default, "e1000" is used. To see a list of valid
network devices, from run "qemu-kvm -device help".

Finally, you can also optionally specify whether the interface should be
configured in "dot1q-tunnel" mode (QinQ) in OVS. If so, the outer VLAN tag will
be set to the minimega VLAN specified as part of the netspec.

The order is:

<bridge>,<VLAN>,<MAC>,<driver>,<qinq>

Examples:

To connect a VM to VLANs 1 and 5:

vm config net 1 5

To connect a VM to VLANs 100, 101, and 102 with specific mac addresses:

vm config net 100,00:00:00:00:00:00 101,00:00:00:00:01:00 102,00:00:00:00:02:00

To connect a VM to VLAN 1 on bridge0 and VLAN 2 on bridge1:

vm config net bridge0,1 bridge1,2

To connect a VM to VLAN 100 on bridge0 with a specific mac:

vm config net bridge0,100,00:11:22:33:44:55

To specify a specific driver, such as i82559c:

vm config net 100,i82559c

To specify the use of "dot1q-tunnel" mode with VLAN 105 as the outer VLAN:

vm config net 105,qinq

If you prefer, you can also use aliases for VLANs:

vm config net DMZ CORE

These aliases will be allocated from the pool of available VLANs and is
namespace-aware (i.e. 'DMZ' in namespace 'foo' will be a different VLAN than
'DMZ' in namespace 'bar'). Internally, this is implemented by concatenating the
namespace name with the VLAN alias (e.g. 'DMZ' in namespace 'foo' becomes
'foo//DMZ'). If you wish to connect VLANs in different namespaces, you may
use/abuse this implementation detail:

namespace bar
vm config net foo//DMZ

Calling vm config net with no arguments prints the current configuration.

vm config preinit

vm config preinit [value]

Containers start in a highly restricted environment. vm config preinit
allows running processes before isolation mechanisms are enabled. This
occurs when the vm is launched and before the vm is put in the building
state. preinit processes must finish before the vm will be allowed to
start.

Specifically, the preinit command will be run after entering namespaces,
and mounting dependent filesystems, but before cgroups and root
capabilities are set, and before entering the chroot. This means that
the preinit command is run as root and can control the host.

For example, to run a script that enables ip forwarding, which is not
allowed during runtime because /proc is mounted read-only, add a preinit
script:

vm config preinit enable_ip_forwarding.sh

Note: this configuration only applies to containers.

vm config qemu

vm config qemu [value]

Set the QEMU binary name to invoke. Relative paths are ok.

Note: this configuration only applies to KVM-based VMs.

Default: "kvm"

vm config qemu-append

vm config qemu-append [value]...

Add additional arguments to be passed to the QEMU instance. For example:

vm config qemu-append -serial tcp:localhost:4001

Note: this configuration only applies to KVM-based VMs.

vm config qemu-override

vm config qemu-override
vm config qemu-override <match> <replacement>

Override parts of the QEMU launch string by supplying a string to match, and a
replacement string. Overrides are applied in the order that they are defined


"match" will later overrides will be applied to the overridden launch string.

Note: this configuration only applies to KVM-based VMs.

vm config schedule

vm config schedule [value]

Set a host where the VM should be scheduled.

Note: Cannot specify Schedule and Colocate in the same config.

vm config serial-ports

vm config serial-ports [value]

Specify the serial ports that will be created for the VM to use. Serial
ports specified will be mapped to the VM's /dev/ttySX device, where X
refers to the connected unix socket on the host at
$minimega_runtime/<vm_id>/serialX.

Examples:

To display current serial ports:
vm config serial-ports

To create three serial ports:
vm config serial-ports 3

Note: Whereas modern versions of Windows support up to 256 COM ports,
Linux typically only supports up to four serial devices. To use more,
make sure to pass "8250.n_uarts = 4" to the guest Linux kernel at boot.
Replace 4 with another number.

vm config snapshot

vm config snapshot [true,false]

Enable or disable snapshot mode for disk images and container
filesystems. When enabled, disks/filesystems will have temporary snapshots created
when run and changes will not be saved. This allows a single
disk/filesystem to be used for many VMs.

Default: true

vm config sockets

vm config sockets [value]

Set the number of CPU sockets. If unspecified, QEMU will calculate
missing values based on vCPUs, cores, and threads.

vm config tags

vm config tags
vm config tags <key> [value]

Set tags in the same manner as "vm tag". These tags will apply to all
newly launched VMs.

vm config threads

vm config threads [value]

Set the number of CPU threads per core. If unspecified, QEMU will
calculate missing values based on vCPUs, sockets, and cores.

vm config uuid

vm config uuid [value]

Configures the UUID for a virtual machine. If not set, the VM will be
given a random one when it is launched.

vm config vcpus

vm config vcpus [value]

Configures the number of virtual CPUs to allocate for a VM.

Default: 1

vm config vga

vm config vga [value]

Specify the graphics card to emulate. "cirrus" or "std" should work with
most operating systems.

Default: "std"

vm config virtio-ports

vm config virtio-ports [value]

Specify the virtio-serial ports that will be created for the VM to use.
Virtio-serial ports specified will be mapped to the VM's
/dev/virtio-port/<portname> device, where <portname> refers to the
connected unix socket on the host at
$minimega_runtime/<vm_id>/virtio-serialX.

Examples:

To display current virtio-serial ports:
vm config virtio-ports

To create three virtio-serial ports:
vm config virtio-ports 3

To explicitly name the virtio-ports, pass a comma-separated list of names:

vm config virtio-ports foo,bar

The ports (on the guest) will then be mapped to /dev/virtio-port/foo and
/dev/virtio-port/bar.

vm config volume

vm config volume
vm config volume <key> [value]

Attach one or more volumes to a container. These directories will be
mounted inside the container at the specified location.

For example, to mount /scratch/data to /data inside the container:

vm config volume /data /scratch/data

Commands with the same <key> will overwrite previous volumes:

vm config volume /data /scratch/data2
vm config volume /data
/scratch/data2

Note: this configuration only applies to containers.

vm hotplug

vm hotplug
vm hotplug <add,> <vm target> <filename> [version]
vm hotplug <add,> <vm target> <filename> serial <serial> [version]
vm hotplug <remove,> <vm target> <disk id or all>

Add and remove USB drives to a launched VM.

To view currently attached media, call vm hotplug with the 'show' argument and
a VM name. To add a device, use the 'add' argument followed by the VM
name, and the name of the file to add. For example, to add foo.img to VM foo:

vm hotplug add foo foo.img

The add command will assign a disk ID, shown in "vm hotplug". The optional
parameter allows you to specify whether the drive will appear on the 1.1 or 2.0
USB bus. For USB 1.1:

vm hotplug add foo foo.img 1.1

For USB 2.0:

vm hotplug add foo foo.img 2.0

To remove media, use the 'remove' argument with the VM name and the disk ID.
For example, to remove the drive added above, named 0:

vm hotplug remove foo 0

To remove all hotplug devices, use ID "all" for the disk ID.

See "vm start" for a full description of allowable targets.

vm info

vm info [summary,]

Print information about VMs in tabular form. The .filter and .columns commands
can be used to subselect a set of rows and/or columns. See the help pages for
.filter and .columns, respectively, for their usage. Columns returned by VM
info include:


Additional fields are available for KVM-based VMs:


Additional fields are available for container-based VMs:


The optional summary flag limits the columns to those denoted with a '*'.

Examples:

Display a list of all IPs for all VMs:
.columns ip,ip6 vm info

Display information about all VMs:
vm info

vm launch

vm launch
vm launch <kvm,> <name or count> [config]
vm launch <container,> <name or count> [config]

Launch virtual machines in a paused state, using the parameters defined leading
up to the launch command. Any changes to the VM parameters after launching will
have no effect on launched VMs.

When you launch a VM, you supply the type of VM in the launch command. The
supported VM types are:


If you supply a name instead of a number of VMs, one VM with that name will be
launched. You may also supply a range expression to launch VMs with a specific
naming scheme:

vm launch kvm foo[0-9]

Note: VM names cannot be integers or reserved words (e.g. "all").

Users may specify a saved config explicity rather than use the current one, for
example:

vm config save endpoint
[other commands]
vm launch kvm 5 endpoint

If queueing is enabled (see "ns"), VMs will be queued for launching until "vm
launch" is called with no additional arguments. This allows the scheduler to
better allocate resources across the cluster.

vm migrate

vm migrate
vm migrate <vm name> <filename>

Migrate runtime state of a VM to disk, which can later be booted with vm config
migrate.

Migration files are written to the files directory as specified with -filepath.
On success, a call to migrate a VM will return immediately. You can check the
status of in-flight migrations by invoking vm migrate with no arguments.

vm net

vm net <add,> <vm target> [netspec]...
vm net <connect,> <vm target> <tap position> <vlan> [bridge]
vm net <disconnect,> <vm target> <tap position>
vm net <bond,> <vm target> <interface indexes> <active-backup,balance-slb,balance-tcp> <active,passive,off> [qinq,]
vm net <bond,> <vm target> <interface indexes> <active-backup,balance-slb,balance-tcp> <active,passive,off> name <name> [qinq,]
vm net <bond,> <vm target> <interface indexes> <active-backup,balance-slb,balance-tcp> <active,passive> <no-lacp-fallback,> [qinq,]
vm net <bond,> <vm target> <interface indexes> <active-backup,balance-slb,balance-tcp> <active,passive> <no-lacp-fallback,> name <name> [qinq,]

Add, disconnect, or move existing network connections for one or more VMs. See "vm
start" for a full description of allowable targets.

To add a network connection, you can specify the same options as you do when you add
connections via vm config when launching VMs. See "vm config net" for more details.

You will need to specify the VLAN of which the interface is a member. Optionally, you may
specify the brige the interface will be connected on. You may also specify a MAC address for
the interface. Finally, you may also specify the network device for qemu to use. By default,
"e1000" is used. The order is:

<bridge>,<VLAN>,<MAC>,<driver>

So to add an interface to a vm called vm-0 that is a member of VLAN 100, with a specified MAC
address, you can use:

vm net add vm-0 100,00:00:00:00:00:00

Network connections are indicated by their position in vm net (same order in vm
info) and are zero indexed. For example, to disconnect the first network
connection from a VM named vm-0:

vm net disconnect vm-0 0

To disconnect the second interface:

vm net disconnect vm-0 1

To move a connection, specify the interface number, the new VLAN tag and
optional bridge:

vm net vm-0 0 100 mega_bridge

If the bridge name is omitted, the interface will be reconnected to the same
bridge that it is already on. If the interface is not connected to a bridge, it
will be connected to the default bridge, "mega_bridge".

To create a bond comprised of two or more interfaces on a VM, use 'vm net bond'.
For example, to create an 'active-backup' bond with interfaces 1 and 2 on VM foo
with LACP set to active:

vm net bond foo 1,2 active-backup active

There are three bond modes supported: active-backup, balance-slb, and
balance-tcp, and three LACP modes supported: active, passive, and off. To
disable the bond if LACP negotiation fails instead of falling back to
active-backup mode, provide the 'no-lacp-fallback' option.

Bonds can also be configured in "dot1q-tunnel" mode (QinQ) in OVS with the
"qinq" option. If configured in "dot1q-tunnel" mode, the outer VLAN tag will be
set to the VLAN the bonded interfaces originally belonged to. Note that a bond
will also be configured in "dot1q-tunnel" mode if at least one of the bonded
interfaces was configured in "dot1q-tunnel" mode, even without the "qinq"
option.

vm qmp

vm qmp <vm name> <qmp command>

Issue a JSON-encoded QMP command. This is a convenience function for accessing
the QMP socket of a VM via minimega. vm qmp takes two arguments, a VM name,
and a JSON string, and returns the JSON encoded response. For example:

vm qmp 0 '{ "execute": "query-status" }'
{"return":{"running":false,"singlestep":false,"status":"prelaunch"}}

vm screenshot

vm screenshot <vm name> [maximum dimension]
vm screenshot <vm name> file <filename> [maximum dimension]

Take a screenshot of the framebuffer of a running VM. The screenshot is saved
in PNG format as "screenshot.png" in the VM's runtime directory (by default
/tmp/minimega/<vm id>/screenshot.png).

An optional argument sets the maximum dimensions in pixels, while keeping the
aspect ratio. For example, to set either maximum dimension of the output image
to 100 pixels:

vm screenshot foo 100

The screenshot can be saved elsewhere like this:

vm screenshot foo file /tmp/foo.png

You can also specify the maximum dimension:

vm screenshot foo file /tmp/foo.png 100

vm snapshot

vm snapshot
vm snapshot <vm name> <state filename> <disk filename>

Write VM state (migrate) and disk to file, which can later be booted with 'vm config
migrate ...' and 'vm config disk ...', respectively.

Saved migrate and disk files are written to the files directory as specified with
-filepath. On success, a call to snapshot a VM will return immediately. You can
check the status of in-flight snapshots by invoking vm snapshot with no arguments.

vm tag

vm tag <vm target> [key or all]
vm tag <vm target> <key> <value>

Display or set a tag for one or more virtual machines. See "vm start" for a
full description of allowable targets.

Tags are key-value pairs. A VM can have any number of tags associated with it.
They can be used to attach additional information to a virtual machine, for
example specifying a VM "group", or the correct rendering color for some
external visualization tool.

To set a tag "foo" to "bar" for VM 2:

vm tag 2 foo bar

To read a tag:

vm tag <vm target> <key or all>

vm top

vm top [duration]

View system resource utilization per VM. This is measured from the host and may
differ from what is reported by the guest.

The optional duration specifies the length of the sampling window in seconds.
The command will block for at least this long while it measures usage. The
default duration is one second.

Returned columns include:


Host and Other Commands

host

host
host <cpucommit,>
host <cpus,>
host <load,>
host <memcommit,>
host <memtotal,>
host <memused,>
host <name,>
host <netcommit,>
host <rx,>
host <tx,>
host <uptime,>
host <vms,>
host <vmlimit,>

Report information about hosts in the current namespace:


All VM-based stats are computed across namespaces.

background

background <command>...

Execute a command under the credentials of the running user.

Commands run in the background and control returns immediately. Any output is
logged at the "info" level.

bridge

bridge
bridge <config,> <bridge> <config>
bridge <trunk,> <bridge> <interface>
bridge <notrunk,> <bridge> <interface>
bridge <tunnel,> <vxlan,gre> <bridge> <remote ip> [key]
bridge <notunnel,> <bridge> <interface>
bridge <destroy,> <bridge>

When called with no arguments, display information about all managed bridges.

To add a trunk interface to a specific bridge, use 'bridge trunk'. For example,
to add interface bar to bridge foo:

bridge trunk foo bar

To create a vxlan or GRE tunnel to another bridge, use 'bridge tunnel'. For
example, to create a vxlan tunnel to another bridge with IP 10.0.0.1:

bridge tunnel vxlan mega_bridge 10.0.0.1

Note: bridge is not a namespace-aware command.

capture

capture <netflow,> <bridge,> <bridge> <filename>
capture <netflow,> <bridge,> <bridge> <tcp,udp> <hostname:port>
capture <netflow,> <delete,> bridge <name>
capture <netflow,> <timeout,> [timeout in seconds]
capture <pcap,> bridge <bridge> <filename>
capture <pcap,> <delete,> bridge <bridge>
capture
capture <pcap,> vm <vm name> <interface index> <filename>
capture <pcap,> <delete,> vm <vm name>
capture <pcap,> <snaplen,> [size]
capture <pcap,> <filter,> [bpf]
capture <netflow,> <mode,> [raw,ascii]
capture <netflow,> <gzip,> [true,false]

Note: the capture API is not fully namespace-aware and should be used with
caution. See notes below.

Capture experiment data including netflow and PCAP. Netflow capture obtains
netflow data from any local openvswitch switch, and can write to file, another
socket, or both. Netflow data can be written out in raw or ascii format, and
file output can be compressed on the fly. Multiple netflow writers can be
configured. There are several APIs to configure new netflow captures:

capture netflow mode [raw,ascii]
capture netflow gzip [true,false]
capture netflow timeout [timeout]

PCAP capture can be from a bridge or VM interface. To set the snaplen or filter
for new PCAP captures, use:

capture pcap snaplen <size>
capture pcap filter <bpf>

Examples:

# Capture netflow for mega_bridge to foo.netflow
capture netflow bridge mega_bridge foo.netflow

# Capture all bridge foo traffic to foo.pcap
capture pcap bridge foo foo.pcap

# Capture the 0-th interface for VM foo to foo.pcap
capture pcap vm foo 0 foo.pcap

When run without arguments, capture prints all running captures. To stop a
capture, use the delete commands:

capture netflow delete bridge <bridge>
capture pcap delete bridge <bridge>
capture pcap delete vm <name>

To stop all captures of a particular kind, replace <bridge> or <vm> with "all".
If a VM has multiple interfaces and there are multiple captures running,
calling "capture pcap delete vm <name>" stops all the captures for that VM. To
stop all captures of all types, use "clear capture".

Notes with namespaces:
* Capturing traffic directly from the bridge (as PCAP or netflow) is not

recommended if different namespaces share the same bridge. If this is the
case, the captured traffic would contain data from across namespaces.
* Due to the way Open vSwitch implements netflow, there can be only one

netflow object per bridge. This means that the netflow timeout is shared
across namespaces. Additionally, note that the API is also not
bridge-specific.

Due to the above intricacies, the following commands only run on the local
minimega instance:

capture <netflow,> <bridge,> <bridge> <filename>
capture <netflow,> <bridge,> <bridge> <tcp,udp> <hostname:port>
capture <netflow,> <delete,> bridge <name>
capture <netflow,> <timeout,> [timeout in seconds]
capture <pcap,> bridge <bridge> <filename>
capture <pcap,> <delete,> bridge <name>

cc

cc
cc <listen,> <port>
cc <clients,>
cc <filter,> [filter]...
cc <commands,>
cc <prefix,> [prefix]
cc <send,> <file>...
cc <recv,> <file>...
cc <exec,> <command>...
cc <background,> <command>...
cc <process,> <list,> <vm name, uuid or all>
cc <process,> <kill,> <pid or all>
cc <process,> <killall,> <name>
cc <log,> level <debug,info,warn,error,fatal>
cc <responses,> <id or prefix or all> [raw,]
cc <tunnel,> <vm name or uuid> <src port> <host> <dst port>
cc <rtunnel,> <src port> <host> <dst port>
cc <delete,> <command,> <id or prefix or all>
cc <delete,> <response,> <id or prefix or all>
cc <test-conn,> <tcp,udp> <ip or fqdn> <port> wait <timeout> [base64 udp packet]

Command and control for VMs running the miniccc client. Commands may include
regular commands, backgrounded commands, and any number of sent and/or received
files. Commands will be executed in command creation order. For example, to
send a file 'foo' and display the contents on a remote VM:

cc send foo
cc exec cat foo

Files to be sent must be in the filepath directory, as set by the -filepath
flag when launching minimega.

Executed commands can have their stdio tied to pipes used by the plumb and pipe
APIs. To use named pipes, simply specify stdin, stdout, or stderr as a
key=value pair. For example:

cc exec stderr=foo cat server.log
cc background stdin=foo stdout=bar /usr/bin/program

Responses are organized in a structure within <filepath>/miniccc_responses, and
include subdirectories for each client response named by the client's UUID.
Responses can also be displayed on the command line with the 'responses'
command.

Filters may be set to limit which clients may execute a posted command. For
example, to filter on VMs that are running windows and have a specific IP.

cc filter os=windows ip=10.0.0.1

Users can also filter by VM tags. For example, to filter on VMs that have the
tag with key foo and value bar set:

cc filter tag=foo:bar

If users wish, they may drop the tag= prefix and key=value pairs will be
treated as tags:

cc filter foo=bar

Users can also filter by any column in "vm info" using a similar syntax:

cc filter name=server
cc filter vlan=DMZ

"vm info" columns take precedance over tags when both define the same key.

"cc mount" allows direct access to a guest's filesystem over the command and
control connection. When given a VM uuid or name and a path, the VM's
filesystem is mounted to the local machine at the provided path. "cc mount"
without arguments displays the existing mounts. Users can use "clear cc mount"
to unmount the filesystem of one or all VMs. This should be done before killing
or stopping the VM ("clear namespace <name>" will handle this automatically).

"cc test-conn" allows users to test network connectivity from a guest to the
given IP or domain name and port. The wait timeout should be specified as a Go
duration string (e.g. 5s, 1m). If "udp" is used, a "base64 udp packet" that will
generate a valid response must be specified. Results of the test will be written
to the command's STDOUT file, whether it passed or failed. An example test is as
follows:

cc test-conn tcp 10.0.0.68 443 wait 10s

If the above test passes, STDOUT for the command will contain the following:

10.0.0.68:443 | pass

If it fails, STDOUT will instead contain the following:

10.0.0.68:443 | fail

For more documentation, see the article "Command and Control API Tutorial".

cc mount

cc mount
cc mount <uuid or name> [path]

check

check

minimega maintains a list of external packages that it depends on, such as
qemu. Calling check will attempt to find each of these executables in the
avaiable path and check to make sure they meet the minimum version
requirements. Returns errors for all missing executables and all minimum
versions not met.

clear all

clear all


you can get without restarting minimega. Restarting minimega is preferable.

clear capture

clear capture [netflow,pcap]

Resets state for captures across the namespace. See "help capture" for more
information.

clear cc

clear cc
clear cc <commands,>
clear cc <filter,>
clear cc <prefix,>
clear cc <responses,>

Resets state for the command and control infrastructure provided by minimega.
See "help cc" for more information.

clear cc mount

clear cc mount [uuid or name or path]

clear deploy flags

clear deploy flags

Reset the deploy flags to their default value, which is equal to the launch
flags used when launching minimega.

clear history

clear history

Reset the command history. See "help history" for more information.

clear log

clear log
clear log <file,>
clear log <mesh,>
clear log <level,>
clear log <stderr,>
clear log <filter,>
clear log <syslog,>
clear log <ring,>

Resets state for logging. See "help log ..." for more information.

clear namespace

clear namespace [name]

Without an argument, "clear namespace" will reset the namespace to the default
namespace, minimega.

With an argument, "clear namespace <name>" will destroy the specified
namespace, cleaning up all state associated with it. You may use "all" to
destroy all namespaces. This command is broadcast to the cluster to clean up
any remote state as well.

clear optimize

clear optimize
clear optimize <affinity,> [filter,]
clear optimize <hugepages,>
clear optimize <ksm,>

Resets state for virtualization optimizations. See "help optimize" for more
information.

clear pipe

clear pipe [pipe]
clear pipe <pipe> <mode,>
clear pipe <pipe> <log,>
clear pipe <pipe> <via,>

clear plumb

clear plumb [pipeline]...

clear qos

clear qos <vm target> [tap index]

Remove QoS constraints from a VM's interface. To clear QoS from all interfaces
for a VM, use the wildcard:

clear qos foo all

See "vm start" for a full description of allowable targets.

clear router

clear router
clear router <vm>
clear router <vm> <rid,>
clear router <vm> <interface,>
clear router <vm> <interface,> <network>
clear router <vm> <interface,> <network> <IPv4/MASK or IPv6/MASK or dhcp or all> [lo,]
clear router <vm> <dhcp,>
clear router <vm> <dhcp,> <listen address>
clear router <vm> <dhcp,> <listen address> <range,>
clear router <vm> <dhcp,> <listen address> <router,>
clear router <vm> <dhcp,> <listen address> <dns,>
clear router <vm> <dhcp,> <listen address> <static,>
clear router <vm> <dhcp,> <listen address> <static,> <mac>
clear router <vm> <dns,>
clear router <vm> <dns,> <ip>
clear router <vm> <upstream,>
clear router <vm> <gw,>
clear router <vm> <ra,>
clear router <vm> <ra,> <subnet>
clear router <vm> <route,>
clear router <vm> <route,> <static,namedstatic>
clear router <vm> <route,> <static,> <network or all> [staticroutename]
clear router <vm> <route,> <ospf,>
clear router <vm> <route,> <ospf,> <area>
clear router <vm> <route,> <ospf,> <area> <network>
clear router <vm> <route,> <ospf,> <area> <export,> <Ipv4/Mask or staticroutename>
clear router <vm> <route,> <bgp,> <processname>
clear router <vm> <route,> <bgp,> <processname> <rrclient,>
clear router <vm> <route,> <bgp,> <processname> <local,neighbor>
clear router <vm> <fw,>

clear tap

clear tap
clear tap <mirror,> [name]
clear tap <mirror,> <vm name> <interface index or all>

Reset state for taps. To delete individual taps, use "tap delete".

"clear tap mirror" can be used to delete one or all mirrors. Mirrors are
identified by the destination for the mirror since a source can have multiple
mirrors. "clear tap" also deletes all mirrors.

Only affects taps on the local node.

clear vlans

clear vlans [prefix]

Clear one or more aliases, freeing the VLANs for reuse. You should only clear
allocated VLANs once you have killed all the VMs connected to them.

By default, "clear vlans" only clears aliases for the current namespace. If
given "all" as the prefix, all state about managed VLANs is cleared across
*all* namespaces, including blacklisted VLANS. You should only use this if you
want a completely clean slate.

clear vnc

clear vnc

Resets the state for VNC recordings. See "help vnc" for more information.

debug

debug
debug <memory,> <file>
debug <cpu,> <start,> <file>
debug <cpu,> <stop,>
debug <goroutine,> <file>

debug can help find and resolve issues with minimega. Without arguments, debug
prints the go version, the number of goroutines, and the number of cgo calls.

With arguments, debug writes files that can be read using "go tool pprof":


deploy

deploy <launch,> <hosts>
deploy <launch,> <hosts> <user> [sudo,]
deploy <flags,> [minimega flags]...
deploy <stdout,> [path]
deploy <stderr,> [path]

deploy copies and runs minimega on remote nodes, facilitating the deployment of
minimega to a cluster. By default, deploy will launch minimega with the same
flags used when starting this minimega, and add the -nostdin flag so that the
remote minimega can be backgrounded. For example, to launch minimega on nodes
kn1 and kn2:

deploy launch kn[1-2]

deploy uses scp/ssh to copy and run minimega. By default, minimega will attempt
to login to remote nodes using the current user. This can be changed by
providing a username. If using a different username, you can optionally specify
the use of sudo when launching minimega (you typically need to run minimega as
root).

In order to override the flags passed to remote minimega instances, provide
flags with 'deploy flags'. For example:

deploy flags -base=/opt/minimega -level=debug

To customize stdout and stderr, use 'deploy stdout' and 'deploy stderr':

deploy stdout /var/log/minimega.out
deploy stderr /var/log/minimega.err

By default, stdout and stderr are written to /dev/null.

disk

disk <create,> <qcow2,raw> <image name> <size>
disk <snapshot,> <image> [dst image]
disk <inject,> <image> files <files like /path/to/src:/path/to/dst>...
disk <inject,> <image> options <options> files <files like /path/to/src:/path/to/dst>...
disk <info,> <image>

Manipulate qcow disk images. Supports creating new images, snapshots of
existing images, and injecting one or more files into an existing image.

Example of creating a new disk:

disk create qcow2 foo.qcow2 100G

The size argument is the size in bytes, or using optional suffixes "k"
(kilobyte), "M" (megabyte), "G" (gigabyte), "T" (terabyte).

Example of taking a snapshot of a disk:

disk snapshot windows7.qc2 window7_miniccc.qc2

If the destination name is omitted, a name will be randomly generated and the
snapshot will be stored in the 'files' directory. Snapshots are always created
in the 'files' directory.

To inject files into an image:

disk inject window7_miniccc.qc2 files "miniccc":"Program Files/miniccc"

Each argument after the image should be a source and destination pair,
separated by a ':'. If the file paths contain spaces, use double quotes.
Optionally, you may specify a partition (partition 1 will be used by default):

disk inject window7_miniccc.qc2:2 files "miniccc":"Program Files/miniccc"

You may also specify that there is no partition on the disk, if your filesystem
was directly written to the disk (this is highly unusual):

disk inject partitionless_disk.qc2:none files /miniccc:/miniccc

You can optionally specify mount arguments to use with inject. Multiple options
should be quoted. For example:

disk inject foo.qcow2 options "-t fat -o offset=100" files foo:bar

Disk image paths are always relative to the 'files' directory. Users may also
use absolute paths if desired. The backing images for snapshots should always
be in the files directory.

dnsmasq

dnsmasq
dnsmasq start <listen address> <low dhcp range> <high dhcp range> [config]
dnsmasq start <config>
dnsmasq kill <id or all>

Start a dhcp/dns server on a specified IP with a specified range. For example,
to start a DHCP server on IP 10.0.0.1 serving the range 10.0.0.2 -
10.0.254.254:

dnsmasq start 10.0.0.1 10.0.0.2 10.0.254.254

To start only a from a config file:

dnsmasq start /path/to/config

To list running dnsmasq servers, invoke dnsmasq with no arguments. To kill a
running dnsmasq server, specify its ID from the list of running servers. For
example, to kill dnsmasq server 2:

dnsmasq kill 2

To kill all running dnsmasq servers, pass all as the ID:

dnsmasq kill all

dnsmasq will provide DNS service from the host, as well as from /etc/hosts. You
can specify an additional config file for dnsmasq by providing a file as an
additional argument.

dnsmasq start 10.0.0.1 10.0.0.2 10.0.254.254 /tmp/dnsmasq-extra.conf

NOTE: If specifying an additional config file, you must provide the full path
to the file.

dnsmasq configure

dnsmasq configure <ID> <ip,>
dnsmasq configure <ID> <ip,> <mac address> <ip>
dnsmasq configure <ID> <dns,>
dnsmasq configure <ID> <dns,> <ip> <hostname>
dnsmasq configure <ID> <dns,> <upstream,>
dnsmasq configure <ID> <dns,> <upstream,> server <ip>
dnsmasq configure <ID> <options,>
dnsmasq configure <ID> <options,> <optionstring>

Configuration options for running dnsmasq instances. Define a static IP
allocation, specify a hostname->IP mapping for DNS, configure upstream DNS
servers (useful when forwarding/NAT is enabled), or set DHCP options.

To list all existing static IP allocations on the first running dnsmasq
server, do the following:

dnsmasq configure 0 ip

To set up a static IP allocation for a VM with the MAC address
00:11:22:33:44:55:

dnsmasq configure 0 ip 00:11:22:33:44:55 172.17.0.50

To see DNS entries:

dnsmasq configure 0 dns

To add a DNS entry:

dnsmasq configure 0 dns 172.17.0.50 example.com

To see upstream DNS servers:

dnsmasq configure 0 upstream

To add an upstream DNS server:

dnsmasq configure 0 upstream server 1.1.1.1

To see a list of all DHCP options:

dnsmasq configure 0 options

To add a DHCP option:

dnsmasq configure 0 options option:dns-server,172.17.0.254

echo

echo [args]...

file

file <list,>
file <list,> <path> [recursive,]
file <get,> <file>
file <stream,> <file>
file <delete,> <file>
file <status,>

file allows you to transfer and manage files served by minimega in the
directory set by the -filepath flag (default is 'base'/files).

To list files currently being served, issue the list command with a directory
relative to the served directory:

file list /foo

Issuing "file list /" will list the contents of the served directory.

Files can be deleted with the delete command:

file delete /foo

If a directory is given, the directory will be recursively deleted.

Files are transferred using the get command. When a get command is issued, the
node will begin searching for a file matching the path and name within the mesh.
If the file exists, it will be transferred to the requesting node. Which file is
transferred over the mesh depends on the mode minimega is running in (see the
"File transfer with minimega" article for details). When a file transfer begins,
control will return to minimega while the transfer completes. If the -hashfiles
flag is disabled (the default), and multiple files with the same name but
different content exist across the mesh, the "file get" behavior for the file is
undefined.

If a directory is specified, that directory will be recursively transferred to
the node.

To see files that are currently being transferred, use the status command:

file status

You can also supply globs (wildcards) with the * operator. For example:

file get *.qcow2
file delete *.qcow2

The stream command allows users to stream files through the Response. Each part
of the file is returned as a separate response which can then be combined to
form the original file. This command blocks until the stream is complete.

help

help [command]...

Show help on a command. If called with no arguments, show a summary of all
commands.

history

history

history displays a list of all the commands that have been invoked since
minimega started on this host, or since the last time the history was cleared.
History includes only valid commands and comments. Invalid lines and blank
lines are not recorded. There are some commands that interact differently with
history, namely read. Instead of recording the "read" command in the history,
minimega records all the valid commands executed from the read file in the
history. This allows the full execution history to be listed using history.

log file

log file [file]

Log to a file. To disable file logging, call "clear log file".

log filter

log filter [filter]

Control what data gets logged based on matching text. For example, to filter
out all logging messages containing the word "foo":

log filter foo

log level

log level [debug,info,warn,error,fatal]

Set the log level to one of [debug,info,warn,error,fatal]. Log levels inherit
lower levels, so setting the level to error will also log fatal, and setting
the mode to debug will log everything.

log mesh

log mesh [node]

Log to a mesh node. To disable mesh logging, call "clear log mesh".

log ring

log ring [size]

The log ring contains recent log messages, if it is enabled. By default
the ring is not enabled. When enabling it, the user can specify a size. The
larger the size, the more memory the logs will consume. The log ring can be
cleared by re-enabling it with the same (or different) size.

To disable the log ring, call "clear log ring".

log stderr

log stderr [true,false]

log syslog

log syslog remote <tcp,udp> <address>
log syslog <local,>

Log to a syslog daemon on the provided network and address. For example, to log
over UDP to a syslog server foo on port 514:

log syslog udp foo:514

namespace

namespace [name]
namespace <name> (command)

With no arguments, "namespace" prints summary info about namespaces:


When a namespace is specified, it changes the active namespace or runs a single
command in the different namespace.

ns

ns <hosts,>
ns <add-hosts,> <hostname or range or all>
ns <del-hosts,> <hostname or range or all>
ns <load,>
ns <load,> <cpucommit,>
ns <load,> <netcommit,>
ns <load,> <memcommit,>
ns <queue,>
ns <flush,>
ns <queueing,> [true,false]
ns <schedule,>
ns <schedule,> <dry-run,>
ns <schedule,> <dump,>
ns <schedule,> <mv,> <vm target> <dst>
ns <schedule,> <status,>
ns <bridge,> <bridge> [vxlan,gre]
ns <del-bridge,> <bridge>
ns <snapshot,> [name]
ns <run,> (command)

Display or modify the active namespace.


nuke

nuke

After a crash, the VM state on the machine can be difficult to recover from.
nuke attempts to kill all instances of QEMU, remove all taps and bridges, and
removes the temporary minimega state on the harddisk.

Should be run with caution.

optimize

optimize
optimize <affinity,> <filter,> <filter>
optimize <affinity,> [true,false]
optimize <hugepages,> [path]
optimize <ksm,> [true,false]

Enable or disable several virtualization optimizations, including Kernel
Samepage Merging, CPU affinity for VMs, and the use of hugepages.

To enable/disable Kernel Samepage Merging (KSM):

optimize ksm [true,false]

To enable hugepage support for future VM launches:

optimize hugepages </path/to/hugepages_mount>

To disable hugepage support:

clear optimize hugepages

To enable/disable CPU affinity support for VMs in the namespace:

optimize affinity [true,false]

To set a CPU set filter for the affinity scheduler, for example (to use only
CPUs 1, 2-20):

optimize affinity filter [1,2-20]

If affinity is already enabled, will cause reassignment of affinity for all
running VMs to match the new filter.

To clear a CPU set filter:

clear optimize affinity filter

See note above about reassigning affinity.

To view current CPU affinity mappings (by PID):

optimize affinity

To disable all optimizations, use "clear optimize".

Note: affinity and hugepages can be selectively enabled in particular
namespaces. KSM affects VMs across all namespaces.

pipe

pipe <pipe> <data>
pipe <pipe> <via,> <command>...
pipe
pipe <pipe> <mode,> <all,round-robin,random>
pipe <pipe> <log,> <true,false>

Interact with named pipes. To write to a pipe, simply invoke the pipe API with
the pipe name and value:

pipe foo Hello pipes!

Pipes have several message delivery modes. Based on the mode, messages written
to a pipe will be delivered to one or more readers. Mode "all" copies messages
to all readers, "round-robin" chooses a single reader, in-order, and "random"
selects a random reader.

Pipes can also have "vias", programs through which all written data is passed
before being sent to readers. Unlike pipelines, vias are run for every reader.
This allows for mutating data on a per-reader basis with a single write. For
example, to send a unique floating-point value on a normal distribution with a
written mean to all readers:

pipe foo via normal -stddev 5.0
pipe foo 1.5

Pipes in other namespaces can be referenced with the syntax <namespace>//<pipe>.

plumb

plumb <src> <dst>...
plumb

Create pipelines composed of named pipes and external programs. Pipelines pass
data on standard I/O, with messages split on newlines. Pipelines are
constructed similar to that of UNIX pipelines. For example, to pipeline named
pipe "foo" through "sed" and into another pipe "bar":

plumb foo "sed -u s/foo/moo/" bar

When specifying pipelines, strings that are not found in $PATH are considered
named pipes.

Pipelines can be composed into larger, nonlinear pipelines. For example, to
create a simple tree rooted at A with leaves B and C, simply specify multiple
pipelines:

plumb a b
plumb a c

qos

qos <add,> <vm target> <interface> <loss,> <percent>
qos <add,> <vm target> <interface> <delay,> <duration>
qos <add,> <vm target> <interface> <rate,> <bw> <kbit,mbit,gbit>

Add quality-of-service (qos) constraints on mega interfaces to emulate real
networks. Currently only applies qos constraints on the egress side / transmit
direction. Qos constraints can be stacked with multiple calls to <add>, and
must be specified explicitly. Any existing constraints will be overwritten by
additional calls to <add>. VM can be specified with the same target syntax as
the "vm start" api.

Note that qos is namespace aware, and any qos commands will be matched to
target vms within the currently active namespace.

qos constraints include:


Note: due to limitations of the underlying tool, "tc", you can only add rate or
loss/delay to a VM. Enabling loss or delay will disable rate and vice versa.

Note: qos applies only to traffic received by the VM (which is "egress" traffic


the mega_tap interface on the host) is not policed to the desired rate.

Examples:

Randomly drop packets on the 0th interface for vms foo0, 1, and 2 with
probability 25%

qos add foo[0-2] 0 loss 25

Add a 100ms delay to every packet on the 0th interface for vm foo and bar

qos add foo,bar 0 delay 100ms

Rate limit the 0th interface on all vms in the active namespace to 1mbit/s

qos add all 0 rate 1 mbit

To clear active qos settings, use:

clear qos <vm> <interface|all>

Example:

clear qos foo all

quit

quit [delay]

Quit minimega. An optional integer argument X allows deferring the quit call
for X seconds. This is useful for telling a mesh of minimega nodes to quit.

quit will not return a response to the cli, control socket, or meshage, it will
simply exit. meshage connected nodes catch this and will remove the quit node
from the mesh. External tools interfacing minimega must check for EOF on stdout
or the control socket as an indication that minimega has quit.

read

read <file> [check,]

Read a command file and execute it. This has the same behavior as if you typed
the file in manually. read stops if it reads an invalid command. read does not
stop if a command returns an error. Nested reads are not permitted.

To prevent issues with another script changing the namespace and commands being
run in a different namespace than originally intended, read records the active
namespace when it starts and prepends that namespace to all commands that it
reads from the file. If it reads a command that would change the active
namespace, read updates its state so that the new namespace is prepended
instead.

If the optional argument check is specified then read doesn't execute any of
the commands in the file. Instead, it checks that all the commands are
syntactically valid. This can identify mistyped commands in scripts before you
read them. It cannot check for semantic errors (e.g. killing a non-existent
VM). The check stops at the first invalid command.

router

router <vm>
router <vm> <commit,>
router <vm> <rid,> <id>
router <vm> <log,> <level,> <fatal,error,warn,info,debug>
router <vm> <interface,> <network> <IPv4/MASK or IPv6/MASK or dhcp> [lo,]
router <vm> <dhcp,> <listen address> <range,> <low address> <high address>
router <vm> <dhcp,> <listen address> <router,> <router address>
router <vm> <dhcp,> <listen address> <dns,> <address>
router <vm> <dhcp,> <listen address> <static,> <mac> <ip>
router <vm> <dns,> <ip> <hostname>
router <vm> <upstream,> <ip>
router <vm> <gw,> <gw>
router <vm> <ra,> <subnet>
router <vm> <route,> <static,> <network> <next-hop> [staticroutename]
router <vm> <route,> <ospf,> <area> <network>
router <vm> <route,> <ospf,> <area> <network> <option> <value>
router <vm> <route,> <ospf,> <area> <export,> <Ipv4/Mask or staticroutename>
router <vm> <route,> <bgp,> <processname> <local,neighbor> <IPv4> <asnumber>
router <vm> <route,> <bgp,> <processname> <rrclient,>
router <vm> <route,> <bgp,> <processname> <export,> <all,filter> <filtername>
router <vm> <fw,> <default,> <accept,drop>
router <vm> <fw,> <accept,drop,reject> <in,out> <index> <dst> <proto>
router <vm> <fw,> <accept,drop,reject> <in,out> <index> <src> <dst> <proto>
router <vm> <fw,> chain <chain> <default,> action <accept,drop,reject>
router <vm> <fw,> chain <chain> action <accept,drop,reject> <dst> <proto>
router <vm> <fw,> chain <chain> action <accept,drop,reject> <src> <dst> <proto>
router <vm> <fw,> chain <chain> apply <in,out> <index>

Configure running minirouter VMs running minirouter and miniccc.

Routers are configured by specifying or updating a configuration, and then
applying that configuration with a commit command. For example, to configure a
router on a running VM named 'foo' to serve DHCP on 10.0.0.0/24 with a range of
IPs:

router foo dhcp 10.0.0.0 range 10.0.0.100 10.0.0.200
router foo commit

router takes a number of subcommands:



using DHCP. The interface field is an integer index of the interface defined
with 'vm config net'. You could also specify if that interface will be a
loopback interface For example, to configure the second interface of the
router with a static IP and a loopback witha different IP:

vm config net 100 200
# ...
router foo interface 1 10.0.0.1/24
router foo interface 2 11.0.0.1/32 lo


to set several options including static IP assignments and the default route
and DNS server. For example, to serve a range of IPs, with 2 static IPs
explicitly called out on router with IP 10.0.0.1:

router vm foo dhcp 10.0.0.0 range 10.0.0.2 10.0.0.254
router vm foo dhcp 10.0.0.0 static 00:11:22:33:44:55 10.0.0.10
router vm foo dhcp 10.0.0.0 static 00:11:22:33:44:56 10.0.0.11





subnet.


next-hop, and optionally a name for this router. For example to specify a
static route(s):

router foo route static 0.0.0.0/0 10.0.0.1 default-route

OSPF routes include an area and a network index corresponding to the
interface described in 'vm config net'. You can also specify what networks
to advertise using the export command.

For example, to enable OSPF on area 0 for both interfaces of a router:

vm config net 100 200
# ...
router foo route ospf 0 0
router foo route ospf 0 1

For example, to advertise specific networks, advertise a static route or
use a static route as a filter:

router foo route static 11.0.0.0/24 0 bar-route
router foo route static 12.0.0.0/24 0 bar-route
router foo route ospf 0 export 10.0.0.0/24
router foo route ospf 0 export default-route
router foo route ospf 0 export bar-route

To configure BGP must specify the process name for the specific bgp context, local ip address and AS,
Neighbor ip address and AS, and what networks need to be advertised

For example, local router is in AS 100 with an ip 10.0.0.1 and bgp peer is in AS 200 with an ip of 20.0.0.1
and you want to advterise network 10.0.0.0/24:

router foo route static 10.0.0.0/24 0 foo_out
router foo bgp bar local 10.0.0.1 100
router foo bgp bar neighbor 20.0.0.1 200
router foo bgp bar export filter foo_out

You can set up route reflection for BGP by ussing the rrclient command for that process.
By using the command it indicates that the peer is a bgp client:

router foo bgp bar rrclient


across the orginizations network and is used for various routing protocols ie OSPF

router foo rid 1.1.1.1


globally globally drop all forwarded packets and accept HTTP traffic from any
IP address to host 192.168.0.5 on the interface at index 0 (which is on the
192.168.0.0/24 network):

router foo fw default drop
router foo fw accept out 0 192.168.0.5:80 tcp

Note that we use 'out' here since we're applying the rule to the interface
that's on the same network as the destination. The source and destination does
not have to include a port.

New iptables chains can also be created, providing a method for grouping rules
together instead of adding rules at the global level. Chains are then applied
to one or more interfaces using the interface index. For example, one could
put the previous rule into a chain named "allow-http" and apply it to the
interface at index 0 via the following:

router foo fw chain allow-http default action drop
router foo fw chain allow-http action accept 192.168.0.5:80 tcp
router foo fw chain allow-http apply out 0

shell

shell <command>...

Execute a command under the credentials of the running user.

Commands run until they complete or error, so take care not to execute a command
that does not return.

status updates

status updates [frequency]

View or set how often status updates should be published by long running
commands.

Long running commands, like launching a VM that requires the VM's disk image to
be transferred, can periodically publish status updates back to the original
caller to show progress.

By default, the status update frequency is 3s. Status updates can be disabled by
setting this value to 0. Otherwise, when setting update frequency, valid Go time
units must be used ("5s", "1m", etc.).

tap

tap
tap <create,> <vlan>
tap <create,> <vlan> name <tap name>
tap <create,> <vlan> <dhcp,> [tap name]
tap <create,> <vlan> ip <ip> [tap name]
tap <create,> <vlan> bridge <bridge>
tap <create,> <vlan> bridge <bridge> name [tap name]
tap <create,> <vlan> bridge <bridge> <dhcp,> [tap name]
tap <create,> <vlan> bridge <bridge> ip <ip> [tap name]
tap <mirror,> <src name> <dst name> [bridge]
tap <delete,> <tap name or all>
tap <mirror,> <vm name> <interface index> <vm2 name> <interface2 index>

Control host taps on a named vlan for communicating between a host and any VMs
on that vlan.

Calling tap with no arguments will list all created taps.

To create a tap on a particular vlan, invoke tap with the create command:

tap create <vlan>

For example, to create a host tap with ip and netmask 10.0.0.1/24 on VLAN 5:

tap create 5 ip 10.0.0.1/24

Optionally, you can specify the bridge to create the host tap on:

tap create <vlan> bridge <bridge> ip <ip>

You can also optionally specify the tap name, otherwise the tap will be in the
form of mega_tapX.

Additionally, you can bring the tap up with DHCP by using "dhcp" instead of a
ip/netmask:

tap create 5 dhcp

Tap mirror mirrors packets that traverse the source tap to the destination tap.
Both taps should already exist. You can use taps for VMs from "vm info" or host
taps. For example, to mirror traffic that traverse mega_tapX to mega_tapY on
the default bridge:

tap mirror mega_tapX mega_tapY

Mirroring is also supported via vm names/interface indices. The VM interfaces
should already be on the same bridge. VMs must be colocated.

To delete a host tap, use the delete command and tap name from the tap list:

tap delete <id>

To delete all host taps, use id all, or 'clear tap':

tap delete all

Note: taps created while a namespace is active belong to that namespace and
will only be listed when that namespace is active (or no namespace is active).
Similarly, delete only applies to the taps in the active namespace. Unlike the
"vlans" API, taps with the same name cannot exist in different namespaces.
Create a mirror from one VM interface to another VM interface. The VMs must be
running on the same physical node.

version

version

viz

viz <filename>

Output the current experiment topology as a graphviz readable 'dot' file.

vlans

vlans
vlans <range,>
vlans <range,> <min> <max>
vlans <add,> <alias> <vlan>
vlans <blacklist,> [vlan]

Display information about allocated VLANs. With no arguments, prints out the
known VLAN aliases. The following subcommands are supported:


Note: this command is namespace aware so, for example, adding a range applies
to all *new* VLAN aliases in the current namespace.

vnc

vnc <record,> <kb,fb> <vm name> <filename>
vnc <stop,> <kb,fb> <vm name>
vnc <play,> <vm target> <filename>
vnc <stop,> <vm target>
vnc <pause,> <vm target>
vnc <continue,> <vm target>
vnc <step,> <vm target>
vnc <getstep,> <vm target>
vnc <inject,> <vm target> <cmd>
vnc

Record keyboard and mouse events sent via the web interface to the
selected VM. Can also record the framebuffer for the specified VM so that a
user can watch a video of interactions with the VM.

If record is selected, a file will be created containing a record of mouse
and keyboard actions by the user or of the framebuffer for the VM.

Note: recordings are written to the host where the VM is running.
Playback and interact with a previously recorded vnc kb session file.

If play is selected, the specified file (created using vnc record) will be read
and processed as a sequence of time-stamped mouse/keyboard events to send to
the specified VM(s). See "vm start" for a full description of the allowable
targets. VMs without a valid playback that are part of the target will return a
"kb playback not found" error.

Playbacks can be paused with the pause command, and resumed using continue. The
step command will immediately move to the next event contained in the playback
file. Use the getstep command to view the current vnc event. Calling stop will
end a playback.

VNC playback also supports injecting mouse/keyboard events in the format found
in the playback file. Injected commands must omit the time delta as they are
sent immediately:

vnc inject vm-0 PointerEvent,0,465,245

New playback files can be injected as well:

vnc inject vm-0 LoadFile,foo.kb

Comments in the playback file are logged at the info level. An example is given
below.

#: This is an example of a vnc playback comment
List all running vnc playback/recording instances. See "help vnc" for more information.

write

write <file>

Write the command history to file. This is useful for handcrafting configs on
the minimega command line and then saving them for later use.