VMCP Reference

1. Configuration Parameters
2. userData Templates

When you are requesting a new Virtual Machine you have to specify a URL where the plugin can find the configuration parameters that describe the structure and the functionality of the instance. This URL is called VM Configuration Point (VMCP).

The document itself is a JSON file that describes the session information. For example:

{
    "name": "MyAwesomeVM",
    "secret": "mg041na39123",
    "vcpus": 1,
    "memory": 512,
    "cernvmVersion": "1.18-2",
    "flags": 8,
    "userData": "[amiconfig]\nplugins=cernvm\n[cernvm]\nusers=user:users;password",
    "signature": "01ba4719c80b6fe911b091a7c05124b64eeece964e09c058ef8f9805daca546b"
}

For security purposes, these information must be signed with your private key. For details on how to calculate the signature check the Calculating VMCP Signature document.

When the CernVM Web API Plugin requests the VMCP URL it always appends the following parameters:

cvm_salt	A random string used by the signature calculation algorithm.
cvm_hostid	A random string, unique for every user and for every domain, useful for calculating secrets.

For example, when you request:

core.requestSession("https://example.com/vmcp.php?vm=1123", success_callback, failure_callback );

The plugin will append the other two parameters, eventually requesting:

https://example.com/vmcp.php?vm=1123&cvm_salt=a8h4f9v7h4w7242iuyaf&cvm_hostid=adc83b19e793491b1c6ea0fd8b46cd9f32e592fc

Configuration parameters

The following VMCP parameters are handled by the plugin:

Parameter	Type	Default	Description
name	string	(Required)	The name of the Virtual Machine.
secret	string	(Required)	A secret key used to resume a previously started session.
signature	string	(Required)	A SHA256 value that will be used to validate the authenticity of the data. Check the Calculating VMCP Signature document for more details about this value.
cpus	integer	1	The number of virtual CPUs to allocate to the new VM.
memory	integer	256	The ammount of RAM (in MB) to allocate for the VM.
disk	integer	1024	The size of the scratch disk (in MB) to allocate for the VM.
cernvmVersion	string	"1.17-8"	The version of CernVM-Micro to use as the base operating system.
cernvmFlavor	string	"prod"	The flavor of CernVM-Micro to use as the base operating system.
diskURL	string	""	A URL from which to download the root disk image for the VM. The image must be a gzipped VDI disk image. (If this parameter is specified the *cernvmVersion*, *cernvmFlavor* will be ignored.).
diskChecksum	string	""	A SHA256 checksum of the file in diskURL. This parameter MUST be supplied along with the diskURL in order to validate the integrity of the file.
userData	string	""	The default userData to pass to the newly created Virtual Machine.
flags	integer	0	A bit mask of flags for the newly created VM. Check the Virtual Machine Creation Flags for the accepted values.
apiPort	integer	80	The port in the VM that the plugin will use as for API. The API URL will be calculate like this http://VM_IP:API_Port/.
executionCap	integer	100	The default execution cap for the VM.
canOverride	string	""	A comma-separated list of VMCP parameters that are allowed to be overridden by javascript.
daemonControlled	boolean	false	If set to 1, the instance will be controlled by the idle daemon.
daemonMinCap	integer	0 (%)	When daemonControlled is true, this variable defines the the minimum capping of the VM. If this value is 0 the VM will be paused/suspended. This cap value is set when the user is using his computer.
daemonMaxCap	integer	100 (%)	When daemonControlled is true, this variable defines the the maximum capping of the VM. This cap value is set when the computer is idle.
daemonFlags	integer	0	A bit mask of flags for the idle daemon. Check the Daemon Flags for the accepted values.

userData Templates

It is possible to include macro variables to the userData. The values for those macros can be specified via the start({ }) function.

Each macro follows the following syntax:

${variable_name[:default]}

For example, here are some contextualization information that allows the user to specify his own username and password. If not specified, the default user will be 'user' with no password.

[amiconfig]
plugins=cernvm

[cernvm]
users=${username:user}:users:${password}

You can then specify the values from javascript:

session.start({
   'username': 'john',
   'password': 'secret'
});