vcsim Features

Interacting with vcsim using the vSphere SOAP and REST APIs as you would a real vCenter covers the majority of vcsim use cases. In this document we cover additional features that are specific to vcsim.

Authentication

By default, vcsim allows any non-empty username and password for authentication via the SessionManager.Login() method. To require a specific combination:

% vcsim -username root -password my-password
export GOVC_URL=https://root:my-password@127.0.0.1:8989/sdk GOVC_SIM_PID=22732

Go example

Injecting Virtual Machine properties

The vm.customize command can be used to set many (but not all) guest properties, using the same APIs as you would against a real vCenter. Example:

% govc vm.power -off DC0_H0_VM1

% govc vm.customize -vm DC0_H0_VM1 -name fourtythree -ip 10.0.0.43

% govc vm.power -on DC0_H0_VM1

% govc object.collect -s vm/DC0_H0_VM1 guest.ipAddress guest.hostName
10.0.0.43
fourtythree

% govc vm.ip DC0_H0_VM1
10.0.0.43

Go example

Certain VirtualMachine properties cannot be modified using API methods in a real vCenter environment. Such fields can be populated in vcsim using VirtualMachineConfigSpec.ExtraConfig entries with a SET. prefix. Example:

% govc object.collect -s vm/DC0_H0_VM0 overallStatus
green

% govc vm.change -vm DC0_H0_VM0 -e SET.overallStatus=red

% govc object.collect -s vm/DC0_H0_VM0 overallStatus
red

The following example has the same effect as using the vm.customize command above:

% govc vm.change -vm DC0_H0_VM0 -e SET.guest.ipAddress=10.0.0.42 -e SET.guest.hostName=fourtytwo

% govc object.collect -s vm/DC0_H0_VM0 guest.ipAddress guest.hostName
10.0.0.42
fourtytwo

% govc vm.ip DC0_H0_VM0
10.0.0.42

Go example

Containers as VMs

For the use case of VirtualMachine interaction outside of the API, a container can be tied to the lifecycle of a vcsim VM. The VM guest field is populated with the container's IP address and MAC address. And VirtualMachine lifecycle methods are mapped to the container:

VM State	VM Method	Docker command
poweredOff	PowerOn	start
suspended	PowerOn	unpause
poweredOn	PowerOff	stop
poweredOn	Suspend	pause
poweredOn	Reset	stop ; start
poweredOff	Destroy	rm -f

To use this feature, add a RUN.container key to the VirtualMachineConfigSpec.ExtraConfig field, with a value of the args to pass to docker run. If there is more than 1 argument, the list must be json encoded.

Example:

% govc vm.power -off DC0_H0_VM0
Powering off VirtualMachine:vm-53... OK

% govc vm.change -vm DC0_H0_VM0 -e RUN.container=nginx

% govc vm.power -on DC0_H0_VM0
Powering on VirtualMachine:vm-53... OK

# docker container name includes VM's uuid
% container=vcsim-DC0_H0_VM0-$(govc collect -s vm/DC0_H0_VM0 config.uuid); echo $container
vcsim-DC0_H0_VM0-265104de-1472-547c-b873-6dc7883fb6cb

% docker inspect -f '{{range .NetworkSettings.Networks}}{{.IPAddress}}{{end}}' $container
172.17.0.2

% govc vm.ip DC0_H0_VM0
172.17.0.2

% govc collect -s vm/DC0_H0_VM0 guest.ipAddress
172.17.0.2

% govc collect -s -json vm/DC0_H0_VM0 guest.net
[
  {
    "ipAddress": [
      "172.17.0.2"
    ],
    "macAddress": "02:42:ac:11:00:02",
    "connected": true,
    "deviceConfigId": 4000,
    "ipConfig": {
      "ipAddress": [
        {
          "ipAddress": "172.17.0.2",
          "prefixLength": 16,
          "state": "preferred"
        }
      ]
    }
  }
]

% curl -s http://172.17.0.2 | grep title
<title>Welcome to nginx!</title>

% docker inspect -f '{{.State.Status}}' $container
running

% govc vm.power -off DC0_H0_VM0
Powering off VirtualMachine:vm-53... OK

% docker inspect -f '{{.State.Status}}' $container
exited

% govc vm.destroy DC0_H0_VM0

% docker inspect -f '{{.State.Status}}' $container
Error: No such object: vcsim-DC0_H0_VM0-265104de-1472-547c-b873-6dc7883fb6cb

Go example

Record and Playback

The govc object.save command can be used to save the inventory of running vCenter, an ESXi host or a vcsim instance. By default, the entire inventory is saved including the ServiceInstance, all Managed Objects and their properties. Each object is saved to a .xml file in ObjectContent format. The object files are saved inside a directory, which defaults to ./vcsim-$hostname and can be overridden using the -d flag.

% govc object.save -u user:pass@my-vcenter -d my-vcenter
Saved 164 total objects to "my-vcenter", including:
ClusterComputeResource: 2
Datastore: 6
DistributedVirtualPortgroup: 2
EnvironmentBrowser: 2
Folder: 20
HostDatastoreBrowser: 6
HostSystem: 4
Network: 3
OpaqueNetwork: 30
ResourcePool: 15
VirtualMachine: 29

The vcsim -load flag will populate vcsim with the saved inventory, rather than vcsim's own built-in/default inventory.

Example:

% vcsim -load my-vcenter &

% export GOVC_URL=https://user:pass@127.0.0.1:8989/sdk

% govc find / -type ClusterComputeResource | wc -l
2

% govc find / -type Datastore | wc -l
6

Modifying saved inventory

The properties withing the saved object files can be manually modified to cover cases that the API does not. For example, HostSystem hardware properties cannot be changed using the API.

% vcsim &
export GOVC_URL=https://user:pass@127.0.0.1:8989/sdk GOVC_SIM_PID=16237

% export GOVC_URL=https://user:pass@127.0.0.1:8989/sdk GOVC_SIM_PID=16237

% govc object.collect -type HostSystem / summary.hardware.memorySize
HostSystem:host-20  summary.hardware.memorySize  int64  4294430720
HostSystem:host-32  summary.hardware.memorySize  int64  4294430720
HostSystem:host-39  summary.hardware.memorySize  int64  4294430720
HostSystem:host-46  summary.hardware.memorySize  int64  4294430720

% govc object.save -d vcsim-host-math
Saved 69 total objects to "vcsim-host-math", including:
DistributedVirtualPortgroup: 2
EnvironmentBrowser: 2
Folder: 5
HostSystem: 4
ResourcePool: 2
VirtualMachine: 4

% kill $GOVC_SIM_PID

% xmlstarlet ed -L -u '//propSet[name="summary"]//hardware/memorySize' -v 8588861440 vcsim-host-math/*host-20.xml

% vcsim -load ./vcsim-host-math &

% govc object.collect -type HostSystem / summary.hardware.memorySize
HostSystem:host-20  summary.hardware.memorySize  int64  8588861440 # doubled the memory of this host
HostSystem:host-32  summary.hardware.memorySize  int64  4294430720
HostSystem:host-39  summary.hardware.memorySize  int64  4294430720
HostSystem:host-46  summary.hardware.memorySize  int64  4294430720

Introducing delays

Sometimes, especially when debugging software, it can be useful to introduce delays to simulate network latency or a poorly performing vCenter. There are three command line options for dealing with delays.

delay

Adds a constant delay (expressed in milliseconds) to every call.

Example:

% vcsim -delay 100

method-delay

Adds a specified delay to individual methods. If both -method-delay and -delay are specified, they are added together.

Example:

% vcsim -method-delay PowerOnVM_Task:100,PowerOffVM_Task:50

delay-jitter

Specifies a jitter, i.e. a random value added to or subtracted from the delay. It is specified as a Coefficient of Variation, which is the same as the standard deviation divided by the mean. A reasonable starting value is 0.5, as it gives a nice variation without extreme outliers.

Example:

% vcsim -delay-jitter 0.5