Guest Agent

Windows

You can find the windows guest agent under the guest/win directory.

Compiling guest agent

You may need to install mingw-w64 packages. For example, on Ubuntu, or Debian:

apt-get install gcc-mingw-w64-i686 g++-mingw-w64-i686 mingw-w64-i686-dev mingw-w64-tools gcc-mingw-w64-x86-64 mingw-w64-x86-64-dev g++-mingw-w64-x86-64

Just compile with make. It will produce 2 files: win_agent_32.exe and win_agent_64.exe, for 32 and 64 bit windows guests respectively.

Compiling test files

In order to compile the test files, just use the provided Makefile as follows:

make test_32
make test_64

Linux

You can find the linux guest agent under the guest/linux path.

Compiling guest agent

You may need to install the following packages. For example, on Ubuntu, or Debian:

apt-get install libc6-dev-i386

Just compile with make. It will produce 2 files: linux_agent_32 and linux_agent_64.exe, for 32 and 64 bit linux guests respectively.

Compiling test files

In order to compile the test files, just use the provided Makefile as follows:

make 32bit_test
make 64bit_test

General usage

Configuring guest agent

  • Add plugins.guest_agent: True to your pyrebox.conf
  • (Optionally) modify your guest agent file name.
  • Add the agent configuration to your pyrebox.conf
  • Adjust the configuration appropriately (if you changed the agent file name).
  • Make sure the agent conf file exists and is up to date. This file is automatically generated by the compilation process.
  • Copy the corresponding guest agent (32 or 64 bit version) to the guest VM, and make sure it follows the same name as declared in the configuration name.
  • Start the agent (you can configure the VM to start the agent on every system start-up).
  • Once the agent is started, you can take a snapshot.

Example agent configuration in pyrebox.conf:

[AGENT]
name: win_agent_64.exe
conf: win_agent_64.exe.conf

Using the guest agent

In scripts:

  • Add plugins.guest_agent: True to your pyrebox.conf, or:
  • Add a member to your module named “requirements” containing a list of required plugins/scripts. E.g.: requirements = ["plugins.guest_agent"]
  • Import the plugin in your script: from plugins.guest_agent import guest_agent.
  • Interact with the guest agent using the public interface of this class (guest_agent is a singleton instance of GuestAgentPlugin). See API.

In the IPython shell:

  • If no script loads the guest_agent plugin, you will need to make sure it gets loaded by adding plugins.guest_agent: True to your pyrebox.conf.
  • Interact with the guest agent using the global member agent that is a singleton instance of GuestAgentPlugin. See API.

Examples

The example script provides a custom command that documents how to use the agent in a PyREBox script. The requirements: ["plugins.guest_agent"] member allows you specificy that the scripts needs the guest agent plugin to be loaded in order to work.