minimega API

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.

.csv

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

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

.json

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

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

.headers

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

Enable or disable headers for tabular data.

.annotate

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

Enable or disable hostname annotation for responses.

.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.

.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.

.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

Substring matching can be specified explicity:

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

.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

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.

.record

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

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

.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.

.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

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. Note that this does not cancel the outstanding command - the node receiving the command may still complete - but rather this node will stop waiting on a response.

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

mesh send

mesh send <clients 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.

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.

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

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> [noblock,]
vm launch <container,> <name or count> [noblock,]

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. Currently, 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").

The optional 'noblock' suffix forces minimega to return control of the command line immediately instead of waiting on potential errors from launching the VM(s). The user must check logs or error states from vm info.

The launch behavior changes when namespace are active. If a namespace is active, invocations that include the VM type and the name or number of VMs will be queue until a subsequent invocation that does not include any arguments. This allows the scheduler to better allocate resources across the cluster. The 'noblock' suffix is ignored when namespaces are active.

vm kill

vm kill <target>

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

vm start

vm start <target>

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 stop

vm stop <target>

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.

vm flush

vm flush

Discard information about VMs that have either quit or encountered an error. This will remove any VMs with a state of "quit" or "error" from vm info. Names of VMs that have been flushed may be reused.

vm hotplug

vm hotplug <show,> <vm name>
vm hotplug <add,> <vm name> <filename>
vm hotplug <remove,> <vm name> <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 show. 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.

vm net

vm net <connect,> <vm name> <tap position> <bridge> <vlan>
vm net <disconnect,> <vm name> <tap position>

Disconnect or move existing network connections on a running VM.

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 with 4 network connections:

vm net disconnect vm-0 0

To disconnect the second connection:

vm net disconnect vm-0 1

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

vm net <vm name> 0 bridgeX 100

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 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 cdrom

vm cdrom <eject,> <vm name>
vm cdrom <change,> <vm name> <path>

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

Change a VM to use a new ISO:

vm cdrom change 0 /tmp/debian.iso

"vm cdrom change" implies that the current ISO will be ejected.

vm tag

vm tag <target> [key or all]
vm tag <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 <target> <key or all>

clear vm tag

clear vm tag
clear vm tag <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 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>

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

vm config memory

vm config memory [memory in megabytes]

Set the amount of physical memory to allocate in megabytes.

vm config vcpus

vm config vcpus [number of CPUs]

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

vm config cpu

vm config cpu [cpu]

Set the virtual CPU architecture.

By default, set to 'host' which matches the host architecture. See 'kvm -cpu help' for a list of architectures available for your version of kvm.

vm config net

vm config net [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".

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

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 tag

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

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

vm config append

vm config append [arg]...

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 qemu

vm config qemu [path to qemu]

Set the QEMU process to invoke. Relative paths are ok. When unspecified, minimega uses "kvm" in the default path.

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

vm config qemu-override

vm config qemu-override
vm config qemu-override add <match> <replacement>
vm config qemu-override delete <id or all>

Override parts of the QEMU launch string by supplying a string to match, and a replacement string.

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

vm config qemu-append

vm config qemu-append [argument]...

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 migrate

vm config migrate [path to migration image]

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 disk

vm config disk [path to disk image]...

Attach one or more disks to a vm. Any disk image supported by QEMU is a valid parameter. Disk images launched in snapshot mode may safely be used for multiple VMs.

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

vm config cdrom

vm config cdrom [path to cdrom image]

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 kernel

vm config kernel [path to kernel]

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 initrd

vm config initrd [path to initrd]

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 uuid

vm config uuid [uuid]

Set the UUID for a virtual machine. If not set, minimega will create a random one when the VM is launched.

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

vm config serial

vm config serial [number of serial ports]

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

To create three serial ports: vm config serial 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 virtio-serial

vm config virtio-serial [number of virtio-serial ports]

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-serial

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

vm config snapshot

vm config snapshot [true,false]

Enable or disable snapshot mode when using disk images. When enabled, disks images will be loaded in memory when run and changes will not be saved. This allows a single disk image to be used for many VMs.

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

vm config hostname

vm config hostname [hostname]

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

vm config init

vm config init [init]...

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

vm config preinit

vm config preinit [preinit]

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

vm config filesystem

vm config filesystem [filesystem]

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

This must be specified in order to launch a container.

vm config fifo

vm config fifo [number]

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.

clear vm config

clear vm config
clear vm config <cpu,>
clear vm config <memory,>
clear vm config <net,>
clear vm config <vcpus,>
clear vm config <append,>
clear vm config <cdrom,>
clear vm config <migrate,>
clear vm config <disk,>
clear vm config <initrd,>
clear vm config <kernel,>
clear vm config <qemu,>
clear vm config <qemu-append,>
clear vm config <qemu-override,>
clear vm config <snapshot,>
clear vm config <uuid,>
clear vm config <serial,>
clear vm config <virtio-serial,>
clear vm config <hostname,>
clear vm config <filesystem,>
clear vm config <init,>
clear vm config <preinit,>

Resets the configuration for a provided field (or the whole configuration) back to the default value.

clear vm config tag

clear vm config tag [key]

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

Host and Other Commands

namespace

namespace [name]
namespace <name> (command)

Control and run commands in namespace environments.

nsmod

nsmod <add-host,> <hosts>
nsmod <del-host,> <hosts>

Modify settings of the currently active namespace.

add-host - add comma-separated list of hosts to the namespace. del-host - delete comma-separated list of hosts from the namespace.

clear namespace

clear namespace [name]

Without a namespace, clear namespace unsets the current namespace.

With a namespace, clear namespace deletes the specified namespace.

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 <delete,> <id or all>

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

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.

clear tap

clear tap

Reset state for taps. See "help tap" for more information.

bridge

bridge
bridge <trunk,> <bridge> <interface>
bridge <notrunk,> <bridge> <interface>
bridge <tunnel,> <vxlan,gre> <bridge> <remote ip>
bridge <notunnel,> <bridge> <interface>

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
capture <netflow,>
capture <pcap,>

capture

capture <pcap,> vm <name> <interface index> <filename>
capture <pcap,> <delete,> vm <name>

capture

capture <netflow,> <timeout,> [timeout]
capture <netflow,> <bridge,> <bridge>
capture <netflow,> <bridge,> <bridge> <file,> <filename>
capture <netflow,> <bridge,> <bridge> <file,> <filename> <raw,ascii> [gzip]
capture <netflow,> <bridge,> <bridge> <socket,> <tcp,udp> <hostname:port> <raw,ascii>
capture <netflow,> <delete,> bridge <name>
capture <pcap,> bridge <bridge> <filename>
capture <pcap,> <delete,> bridge <name>

Note: the capture API is not fully namespace-aware and should be used with caution. See note 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.

PCAP capture can be from a bridge or VM interface. No filters are applied, and all data seen on that interface is captured to file.

For example, to capture netflow data on bridge mega_bridge to file in ascii mode and with gzip compression:

capture netflow bridge mega_bridge file foo.netflow ascii gzip

You can change the active flow timeout with:

capture netflow timeout <timeout>

With <timeout> in seconds.

To capture pcap on bridge 'foo' to file 'foo.pcap':

capture pcap bridge foo foo.pcap

To capture pcap on VM 'foo' to file 'foo.pcap', using the 2nd interface on that VM:

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 id with "all". To stop all capture of all types, use "clear capture". 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.

Notes with namespaces: * "capture [netflow,pcap]" lists captures across the namespace * "capture pcap vm ..." captures traffic for a VM in the current namespace * "capture netflow ..." and "capture pcap ..." only run on the local node -- you must manually "mesh send all ..." if you wish to use them. * if you capture traffic from a bridge, you will see traffic from other experiments. * "clear capture" clears captures across the namespace.

clear capture

clear capture [netflow,pcap]

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

cc

cc
cc <clients,>
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 <commands,>
cc <filter,> [filter]...
cc <responses,> <id or prefix or all> [raw,]
cc <tunnel,> <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>

Command and control for virtual machines 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.

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

When a namespace is active, there is an implicit filter for vms with the provided namespace.

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

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.

deploy

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

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

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.

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.

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> <options,>
dnsmasq configure <ID> <options,> <optionstring>

Configuration options for running dnsmasq instances. Define a static IP allocation, specify a hostname->IP mapping for DNS, 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 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

viz

viz <filename>

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

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.

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.

clear history

clear history

Reset the command history. See "help history" 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.

host

host
host <bandwidth,>
host <cpus,>
host <load,>
host <memtotal,>
host <memused,>
host <name,>
host <vms,>
host <vmsall,>
host <uptime,>

Report information about the host:

file

file <list,> [path]
file <get,> <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. If multiple different files exist with the same name, the behavior is undefined. When a file transfer begins, control will return to minimega while the transfer completes.

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

file status

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

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

file get *.qcow2

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 stderr

log stderr [true,false]

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 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

clear log

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

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

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.

help

help [command]...

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

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.

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). Stops on the first invalid command.

debug

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

version

version

echo

echo [args]...

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: optimize hugepages </path/to/hugepages_mount>

To disable hugepage support: clear optimize hugepages

To enable/disable CPU affinity support: 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]

To clear a CPU set filter: clear optimize affinity filter

To view current CPU affinity mappings: optimize affinity

To disable all optimizations see "clear optimize".

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.

qos

qos <add,> <target> <interface> <loss,> <percent>
qos <add,> <target> <interface> <delay,> <duration>
qos <add,> <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>. Virtual machines 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:

Examples:

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

qos add foo[0-2] 0 loss 0.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

clear qos

clear qos <target> [interface]

Remove quality-of-service constraints on a mega interface. This command is namespace aware and will only clear the qos from vms within the active namespace.

Example:

Remove all qos constraints on the 1st interface for the vms foo and bar
clear qos foo,bar 1

router

router <vm>
router <vm> <commit,>
router <vm> <log,> <level,> <fatal,error,warn,info,debug>
router <vm> <interface,> <network> <IPv4/MASK or IPv6/MASK or dhcp>
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> <ra,> <subnet>
router <vm> <route,> <static,> <network> <next-hop>
router <vm> <route,> <ospf,> <area> <network>

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'. For example, to configure the second interface of the
router with a static IP:
vm config net 100 200
# ...
router foo interface 1 10.0.0.1/24
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. OSPF routes include an area and a network index corresponding to
the interface described in 'vm config net'. 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

clear router

clear router
clear router <vm>
clear router <vm> <interface,>
clear router <vm> <interface,> <network>
clear router <vm> <interface,> <network> <IPv4/MASK or IPv6/MASK or dhcp>
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> <ra,>
clear router <vm> <ra,> <subnet>
clear router <vm> <route,>
clear router <vm> <route,> <static,>
clear router <vm> <route,> <static,> <network>
clear router <vm> <route,> <ospf,>
clear router <vm> <route,> <ospf,> <area>
clear router <vm> <route,> <ospf,> <area> <network>

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.

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.

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:

range - view or set the VLAN range add - add an alias blacklist - view or create blacklisted VLAN

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

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.

Note: When no prefix is specified and a namespace is not active, all state about managed VLANs is cleared.

vnc

vnc <record,> <kb,fb> <vm name> <filename>
vnc <stop,> <kb,fb> <vm name>

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.

vnc

vnc <play,> <vm name> <filename>
vnc <stop,> <vm name>
vnc <pause,> <vm name>
vnc <continue,> <vm name>
vnc <step,> <vm name>
vnc <getstep,> <vm name>
vnc <inject,> <vm name> <cmd>

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.

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 host vm_id inject PointerEvent,0,465,245

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

clear vnc

clear vnc

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

vnc

vnc

List all running vnc playback/recording instances. See "help vnc" for more information.

vyatta

vyatta
vyatta <dhcp,>
vyatta <dhcp,> add <network> <gateway or none> <low dhcp range> <high dhcp range> [dns server]
vyatta <dhcp,> delete <network>
vyatta <interfaces,> [net A.B.C.D/MASK or dhcp or none]...
vyatta <interfaces6,> [net IPv6 address/MASK or none]...
vyatta <rad,> [prefix]...
vyatta <ospf,> [network]...
vyatta <ospf3,> [network]...
vyatta <routes,> [network and next-hop separated by comma]...
vyatta <config,> [filename]
vyatta <write,> [filename]

Define and write out vyatta router floppy disk images.

vyatta takes a number of subcommands:

default gateway, and start and stop addresses. For example, to serve dhcp on 10.0.0.0/24, with a default gateway of 10.0.0.1:

vyatta dhcp add 10.0.0.0/24 10.0.0.1 10.0.0.2 10.0.0.254

An optional DNS argument can be used to override the nameserver. For example, to do the same as above with a nameserver of 8.8.8.8:

vyatta dhcp add 10.0.0.0/24 10.0.0.1 10.0.0.2 10.0.0.254 8.8.8.8

Optionally, you can specify "none" for the default gateway.

'none' may be specified. The order specified matches the order of VLANs used in vm_net. This number of arguments must either be 0 or equal to the number of arguments in 'interfaces6' For example:

vyatta interfaces 10.0.0.1/24 dhcp

arguments must either be 0 or equal to the number of arguments in 'interfaces'.

prefixes or "none". Order matches that of interfaces6. For example:

vyatta rad 2001::/64 2002::/64
vyatta ospf 10.0.0.0/24 12.0.0.0/24
vyatta ospf3 eth0 eth1
<network>,<next-hop> ...

For example:

vyatta routes 2001::0/64,123::1 10.0.0.0/24,12.0.0.1

file. For example: vyatta config /tmp/myconfig.boot

random filename will be used and the file placed in the path specified by the -filepath flag. The filename will be returned.

clear vyatta

clear vyatta

Resets state for vyatta. See "help vyatta" for more information.

web

web [port]
web root <path> [port]

Launch the minimega webserver. Running web starts the HTTP server whose port cannot be changed once started. The default port is 9001. To run the server on a different port, run:

web 10000

The webserver requires several resources found in misc/web in the repo. By default, it looks in $PWD/misc/web for these resources. If you are running minimega from a different location, you can specify a different path using:

web root <path/to/web/dir>

You can also set the port when starting web with an alternative root directory:

web root <path/to/web/dir> 10000

NOTE: If you start the webserver with an invalid root, you can safely re-run "web root" to update it. You cannot, however, change the server's port.

Authors

Auto-generated by apigen

Last updated 14 December 2016