Shaken Fist In-Guest Agent¶
The Shaken Fist in-guest agent (sf-agent) is a Python daemon
that runs inside virtual machines managed by
Shaken Fist. It provides a side channel
for the hypervisor to interact with the guest operating system
without requiring network connectivity.
Features¶
- Command execution: Run arbitrary commands inside the guest with configurable I/O priority, environment variables, working directory, and network namespace support.
- File transfer: Upload and download files between the hypervisor and the guest using a chunked, base64-encoded protocol.
- File permissions: Set file permissions using symbolic mode
notation (e.g.
ugo+rw). - System facts: Gather OS distribution information, mounted filesystems, and SSH host keys.
- Health checks: Query systemd status and agent liveness.
How It Works¶
The agent listens on vsock port 1025 for connections from the hypervisor. All communication uses Protocol Buffers for serialization. Each connection is handled in its own thread, allowing multiple concurrent operations.
The hypervisor side of this protocol is implemented in the main Shaken Fist repository.
Installation¶
The agent is installed automatically by Shaken Fist when preparing guest images. For manual installation:
The agent is typically started as a systemd service:
Use --verbose for debug logging:
Further Reading¶
- Protocol Reference -- details of the protobuf message format and command semantics.
- Developer Guide -- how to build, test, and extend the agent.