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

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

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

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

vm <stop,> <vm target>
vm <start,> <vm target>
vm <kill,> <vm target>
vm <flush,>
vm <flush,> <vm 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. 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. Kill one or more running virtual machines. See “vm start” for a full description of allowable targets. 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.

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.

Finally, 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”.

The order is:

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

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 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 and do not replace earlier overrides — if more than override share the same “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

info include:

• id* : the VM ID, as an integer
• name* : the VM name, if it exists
• state* : one of (building, running, paused, quit, error)
• uptime : amount of time since the VM was launched
• namespace* : namespace the VM belongs to
• type* : one of (kvm, container)
• uuid* : QEMU system uuid
• cc_active* : indicates whether cc is connected
• vcpus : the number of allocated CPUs
• memory : allocated memory, in megabytes
• vlan* : vlan, as an integer
• bridge : bridge name
• tap : tap name
• mac : mac address
• ip : IPv4 address
• ip6 : IPv6 address
• bandwidth : stats regarding bandwidth usage
• qos : quality-of-service contraints on network interfaces
• tags : any additional information attached to the VM

Additional fields are available for KVM-based VMs:

• append : kernel command line string
• cdrom : cdrom image
• disk : disk image
• kernel : kernel image
• initrd : initrd image
• migrate : qemu migration image
• pid : pid of qemu process
• serial : number of serial ports
• virtio-serial : number of virtio ports
• vnc_port : port for VNC shim

Additional fields are available for container-based VMs:

• filesystem : root filesystem for the container
• hostname : hostname of the container
• init : process to invoke as init
• preinit : process to invoke at container launch before isolation
• pid : pid of container’s init process
• fifo : number of fifo devices
• console_port : port for console shim

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:

• kvm : QEMU-based vms
• container: Linux containers

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>

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

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 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: – name : name of the VM – namespace : namespace of the VM (when not in a namespace) – virt : virtual memory size (MB) – res : resident memory size (MB) – shr : shared memory size (MB) – cpu : host CPU usage (%) – vcpu : guest CPU usage (%) (KVM only) – time : total CPU time – procs : number of processes inspected (limited to 100) – rx : total received data rate (MB/s) – tx : total transmitted data rate (MB/s)

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

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:

• cpucommit : total cpu commit
• cpus : number of cpus
• load : system load average
• memcommit : total memory commit in MB
• memtotal : total memory in MB
• memused : memory used in MB
• name : name of the machine
• netcommit : total network interface commit
• rx : RX bandwidth stats (MB/s)
• tx : TX bandwidth stats (MB/s)
• uptime : uptime
• vms : number of VMs
• vmlimit : limit based on coschedule values (-1 is no limit)

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 <pcap,> <snaplen,> [size]
capture <pcap,> <filter,> [bpf]
capture <netflow,> <mode,> [raw,ascii]
capture <netflow,> <gzip,> [true,false]
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>

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>

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

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

cc mount

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

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

Runs all the “clear …” handlers on the local instance — as close to nuke as 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 <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 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”:

• memory: sampling of all heap allocations
• cpu: starts CPU profiling (must be stopped before read)
• goroutine: stack traces of all current goroutines

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

echo

echo [args]...

file

file <list,> [path]
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. 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
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 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:

• name : name of the namespace
• vlans : range of VLANs, empty if not set
• active : active or not

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.

• hosts : list hosts
• add-hosts : add comma-separated list of hosts to the namespace
• del-hosts : delete comma-separated list of hosts from the namespace
• load : display or change host load is computed for scheduler, based on:

- cpucommit : total CPU commit divided by number of CPUs (default)
- netcommit : total NIC
- memcommit : total memory commit divided by total memory

• queue : display VM queue
• flush : clear the VM queue
• queueing : toggle VMs queueing when launching (default false)
• schedule : run scheduler (same as “vm launch”)

- dry-run : determine VM placement and print out VM -> host assignments
- dump    : print out VM -> host assignments (after dry-run)
- mv      : manually edit VM placement in schedule (after dry-run)
- status  : display scheduling status

• bridge : create a bridge, defaults to GRE mesh between hosts
• del-bridge: destroy a bridge
• snapshot : take a snapshot of namespace or print snapshot progress
• run : run a command on all nodes in the 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
plumb <src> <dst>...

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:

• loss : packets will be randomly dropped with a specified probability
• delay : delay packets for specified unit of time (ms, ns, etc)
• rate : impose a maximum bandwidth on an interface in kbit, mbit, or gbit

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 on the mega_tap interface on the host) — traffic sent by the VM (“ingress” on 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.

Because reading and executing long files can take a while, the read command releases the command lock that it holds so commands from other clients (including miniweb) can be interleaved. 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>

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:

• ‘log’: Change the log level of the minirouter tool on the VM.
• ‘interface’: Set IPv4 or IPv6 addresses, or configure an interface to assign

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

• ‘dhcp’: Configure one or more DHCP servers on the router. The API allows you

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

• ‘dns’: Set DNS records for IPv4 or IPv6 hosts.
• ‘upstream’: Set upstream server for DNS.
• ‘gw’: Set default gateway which will be used if there is no matching route.
• ‘ra’: Enable neighbor discovery protocol router advertisements for a given

subnet.

• ‘route’: Set static, OSPF, or BGP routes. Static routes include a 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

• ‘rid’: Sets the 32 bit router ID for the router. Typically this ID is unqiue

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

  router foo rid 1.1.1.1

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.

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:

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.

vnc

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,> <kb,fb> <vm name> <filename>
vnc <stop,> <kb,fb> <vm name>
vnc

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.

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