Access from Guest OS

Once a DataSet is present in the VM, the guest OS can access and modify its DataSet entries using a small set of VMware Tools commands.

A guest OS cannot create, delete, or change the attributes of a DataSet. However, once one or more DataSets is present in the VM, the guest OS can obtain a list of DataSets and attributes, and read or write DataSet entries.

The guest OS has read access to DataSet key-value entries. Access from the guest OS does not allow DataSets themselves to be created or deleted, nor their attributes to be modified. The guest OS can modify key values and delete key-value pairs.

Users can access DataSet information using the terminal (CLI) on Windows, Linux, or MacOS using a utility that is part of VMware Tools. In the vmtoolsd template below, you replace directive with one of the DataSet commands below. The --cmd option is implemented as a message from the guest to the host.

vmtoolsd.exe --cmd "directive"
vmtoolsd --cmd "directive"

For example, the following command lists all keys from the DataSet named my-dataset.

$ vmtoolsd --cmd 'datasets-list-keys {"dataset":"my-dataset"}'

Each DataSet command produces JSON output, which on failure will include an error message. JSON schemas are provided in the next section. For easy editing and reuse, JSON can be placed into a file, as described at the end of this section. DataSet commands are presented below, each followed by sample input and results.

datasets-list – Return summary data about any DataSets, such as name and description.

datasets-list

No input required. Sample JSON results on success:

{
  "result" : true,
  "datasets" : [
    { "name":"dataset1", "description":"description of dataset1" },
    { "name":"dataset2", "description":"description of dataset2" },
    { "name":"dataset3", "description":"description of dataset3" }
  ]
}

datasets-query – Return a DataSet's attributes (description, usage, access).

datasets-query <json-document>

Here is an example of <json-document> that might be used to pass directives in the above command:

{
  "dataset": "dsname1"
}

Here is the same JSON used in a vmtoolsd command line:

vmtoolsd --cmd 'datasets-query {"dataset": "dsname1"}'

Sample JSON results; error message only on failure:

{
  "result": true,
  "info": {
    "name": "dsname1",
    "description" : "dsname1 description",
    "used" : 2345,
    "hostAccess" : "READ_WRITE",
    "guestAccess" : "READ_ONLY",
    "omitFromSnapshotAndClone" : true },
  "error-message": ""
}

Sample JSON results on error:

{
  "error-message" : "DataSet dsname2 not found."
}

datasets-get-entry – Get the value of one or more keys in a DataSet. If any key is not defined, it's not an error, but no results are returned for undefined keys.

datasets-get-entry <json-document>

Here is an example of <json-document> that might be used to pass directives the above command:

{
  "dataset" : "ds1",
  "keys" : [ "key1", "key2", "key3" ]
}

Here is an example of results passed back from the command, in JSON format:

{
  "result" : true,
  "entries" : [
      { "key1" : "value1"},
      { "key2" : "value2"},
      { "key3" : "value3"}
   ]
}

datasets-set-entry – Set the value of one or more keys in a DataSet. An individual key can be specified only once, otherwise the operation fails with an error.

datasets-set-entry <json-document>

In this example below, key1 will be set or reset to value1, while key2 will have appended-value2 added after its previous value, which may be null. If there is no entry with "key2" key, then "append" is essentially ignored – a new entry will be created with "key2" key and "appended-value2" value. Append is useful when you want to set a value that is too large for the underlying message transport to handle, so more than one datasets-set-entry is required. You must append in chunks that fit within the message limit, around 63K. Here is how <json-document> might be used to pass those directives to datasets-set-entry:

{
  "dataset" : "ds1",
  "entries": [
    { "key": "key1", "value": "value1" },
    { "key": "key2", "value": "appended-value2", "append": true }
  ]
}

Returns error or success; error message only on failure. Sample JSON results:

{ 
  "result": true
}

datasets-list-keys – Enumerate the keys in a DataSet.

datasets-list-keys <json-document>

Here is an example of <json-document> that might be used to pass directives the above command:

{
  "dataset": "ds1"
}

Sample JSON results; error message only on failure.

{
  "result": true, "error-message": "",
  "keys" : [ "key1", "key2", "key3" ]
}

datasets-delete-entry – deletes one or more entries in a DataSet. If any key is not defined, the operation will fail and the DataSet contents will be unchanged.

datasets-delete-entry <json-document>

Here is an example of <json-document> that might be used to pass directives the above command:

{
  "dataset" : "ds1",
  "keys": [ "key1", "key2", "key3" ]
}

Returns error or success; error message only on failure. Sample JSON results:

{
  "result": true, "error-message": ""
}

JSON in a File

VMware Tools 11.2 added the --cmdfile option to the vmtoolsd command. This option allows directive to be specified in a file rather than on the command line, as in previous examples. Due to the 8KB limit for shell commands on Windows, and the vagaries of escaping shell syntax on MacOS and Linux, the command file option is recommended.

$ vmtoolsd --cmdfile commandFile.sh

Here is what might be in commandFile.sh for the datasets-get-entry command at the beginning of this section.

datasets-get-entry {"dataset": "ds1", "keys": ["key1", "key2", "key3"]}

Python for DataSets

The Guest SDK contains Python sample code that provides an easy-to-use wrapper for DataSets operations. Functions in the util.py file show how to set up Guest RPC and pass JSON objects. The datasets.py program implements all of the commands, as shown in its usage message. See sections above for required arguments.

Usage: datasets [query|list|listkeys|set|get|delete] arguments