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.
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.$ vmtoolsd --cmd 'datasets-list-keys {"dataset":"my-dataset"}'
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" : "DataSetdsname2not 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