These patches for guest-agent add the functionality to execute
commands on
a guest UNIX machine.
These patches add the following interfaces:
guest-pipe-open
guest-exec
guest-exec-status
With these interfaces it's possible to:
* Open an anonymous pipe and work with it as with a file using already
implemented interfaces guest-file-{read,write,flush,close}.
* Execute a binary or a script on a guest machine.
We can pass arbitrary arguments and environment to a new child process.
* Pass redirected IO from/to stdin, stdout, stderr from a child
process to a
local file or an anonymous pipe.
* Check the status of a child process, get its exit status if it
exited or get
signal number if it was killed.
We plan to add support for Windows in the near future using the same
interfaces
we introduce here.
Example of usage:
{"execute": "guest-pipe-open", "arguments":{"mode": "r"}}
{'return': 1000}
{"execute":"guest-exec", "arguments":{ "path": "id", "params": ["user"],
"env": ["MYENV=myvalue"], "handle_stdout": 1000 }}'
{"return": 2636}
{"execute": "guest-exec-status", "arguments": {"pid": 2636}}
{"return":{"exit":0,"handle_stderr":-1,"handle_stdin":-1,"handle_stdout":1000,"signal":-1}}
{"execute": "guest-file-read", "arguments": {"handle": 1000,
"count":128}}
{"return":{"count":58,"buf-b64":"dWlk...","eof":true}}
{"execute": "guest-file-close", "arguments": {"handle": 1000}}
{"return":{}}
These patches are based on the patches proposed by Michael Roth in 2011:
http://lists.gnu.org/archive/html/qemu-devel/2011-12/msg00722.html
We made several modifications to the interfaces proposed by Michael
to simplify
their usage and we also added several new functions:
* Arguments to an executable file are passed as an array of strings.
Before that we had to pass parameters like this:
'params': [ {'param': '-b'}, {'param': '-n1'} ]
Now we may pass them just as an array of strings:
'params': [ '-b', '-n1' ]
* Environment can be passed to a child process.
"env": ["MYENV=myvalue"]
* Removed "detach" argument from "guest-exec" - it never waits for a
child
process to signal. With this change it's possible to return just PID
from
"guest-exec", a user must call "guest-exec-status" to get the status
of a child.
* Removed "wait" argument from "guest-exec-status" - waiting for a
child process
to signal is dangerous, because it may block the whole qemu-ga.
Instead, the
command polls just once a status of a child.
* "guest-exec-status" returns exit status of a child process or a
signal number,
in case a process was killed.
* Simplified the command "guest-pipe-open" - the way how it stores
the pipe
fd's. No additional logic is needed about which end of pipe should
be closed
with "guest-file-close". This way we avoid modifying the interface
of the
existing "guest-file-close".
In the conversation about the original patches there was a suggestion
to merge
"path" and "params" into one single list. But we didn't do so,
because having
separate "path" is similar to exec*() family functions in UNIX. That
way it
looks more consistent.
Changes from v2:
- return code of commands changed to dictionary
- ported to current HEAD
- new way for moving pipe to non-blocking state (universal)
Changes from v1:
- Windows version of the patchset is added
- SIGPIPE processing is added for Unix version of the patchset
- added guest_exec_file_busy() to prevent GuestFileHandle* object
from being
deleted in case it's used in guest-exec command.
Signed-off-by: Olga Krishtal <address@hidden>
Signed-off-by: Denis V. Lunev <address@hidden>
P.S. Michael, this is a working version and could we consider it for
merging
into 2.4? If you still want to use universal GLIB code, we could
re-write this later using standard refactoring way.