In-Guest Communication Limits

Resource constraints impose unavoidable limits on guest to host communications.

Messages from the guest to VMX can be no more than 64KB, including overhead. The VMX sends back at most about 1MB. If the 64KB limit is exceeded, the request fails and an error is returned. This affects several in-guest APIs.

The guest-to-VMX limit affects datasets-set-entries, which is why the append flag exists. If you have a value >63K that must be set, then you should break it into chunks. The first chunk should have the first 63K or so bytes of value, with the append flag either omitted or false. Subsequent chunks should call datasets-set-entries again with the same key, the next chunk of the value, and append flag set true. Iterate until the entire large value has been set.

The VMX-to-guest limit affects datasets-list-keys and datasets-get-entries.

If the full reply is >1MB or so, it includes a context property. If so, then the next chunk of data for that reply will be returned, after another call with the same parameters is sent, plus the context returned by the previous reply. For both datasets-list-keys and datasets-get-entries, any chunking is done at the key level – the key and value are never separated. Confusion might ensue if data changes midway through the process, for example, if vSphere changes the keys or entries involved.

The context is an opaque string. Programs should never try to use anything but what was returned in the previous reply as its value.

The datasets-list-keys limit is unlikely to be encountered in most cases, because it only occurs with >1MB of keynames in a single dataset.

If programs query more than one entry in a single API call, then context can come into play, because the complete reply could be >1MB (any value could be up to 1MB). But this does mean you can get a mix of reply sizes. A datasets-get-entries of one set of keys that lists a small key, a large key, and another small key might result in three replies. The first will include just value1, the second value2 and the third value3.

If you want to circumvent these limits, or have no idea how big the values might be, you can get a single entry at a time. That is less efficient but may be advisable.