The file-read command of the QEMU guest agent previously had several
practical limitations. It always read a fixed 16 MiB block starting at
offset 0, making it impossible to retrieve larger files in multiple
chunks. On busy or resource‑constrained hosts, requests for large files
often timed out because the agent attempted to read and JSON‑encode the
entire 16 MiB block at once.
Binary data was also returned as raw JSON strings with extensive
escaping, which inflated payload size and caused compatibility issues
with some JSON parsers.
This patch extends the file-read method with three new parameters:
- decode — Controls whether the base64‑encoded data returned by the
guest agent should be decoded before being sent back through the API.
When disabled, the base64 string is passed through unchanged, which is
ideal for binary data and mirrors the existing encode parameter of
file-write.
- offset — Allows reading from an arbitrary byte offset within the
file.
- count — Allows requesting a smaller number of bytes than the
internal 16 MiB limit, avoiding unnecessary overhead and reducing
timeout risk.
With these additions, the behavior now mirrors standard file operations
(fopen, fseek, fread). Reading beyond EOF returns zero bytes.
Seek can choose any non-negative position within the file, without
bounds checking. Reading out of bounds returns 0 bytes.
This allows conveniently reading an entire file in a robust way:
while(truncated && content.length != 0) {}
and also enables things like tailing a changing file.
This makes the file-read command significantly more flexible.
All parameter additions were done in a backwards-compatible fashion.
Markus Ebner (1):
close #7342: Extend qga file-read with chunked access for large files
src/PVE/API2/Qemu/Agent.pm | 54 ++++++++++++++++++++++++++++++++------
1 file changed, 46 insertions(+), 8 deletions(-)
--
2.53.0
