QEMU Guest Agent Wrapper

A professional Python wrapper for communicating with QEMU Guest Agent (QGA) via Unix socket, enabling remote management of QEMU/KVM virtual machines from the host system.

🚀 Quick Start

# Activate virtual environment
source venv/bin/activate

# Test connectivity
python src/qga ping

# Get system information
python src/qga osinfo

# Execute a command
python src/qga exec whoami

📁 Project Structure

qga-wrapper/
├── src/                      # Source code
│   ├── qga_wrapper.py       # Core wrapper library
│   └── qga_cli.py           # Command-line interface
├── docs/                     # Documentation
│   ├── README.md            # Comprehensive guide
│   ├── DEVELOPMENT.md       # Implementation details
│   └── QUICK_START.md       # Quick reference
├── config/                   # Configuration files
│   └── config.yaml          # Default configuration
├── examples/                 # Usage examples
│   └── example_usage.py     # Python API examples
├── data/                     # Data files
│   └── basic_info.json      # QGA capability info
├── tests/                    # Test results
│   └── TEST_RESULTS.md      # Comprehensive test report
├── venv/                     # Virtual environment
├── .gitignore               # Git ignore rules
├── README.md                 # Project overview
└── requirements.txt          # Python dependencies

📖 Documentation

• Quick Start Guide - Get started in 5 minutes
• Full Documentation - Comprehensive usage guide
• Development Notes - Architecture & implementation details

✨ Features

• Command Execution: Run arbitrary commands in the guest VM
• User Management: Remote password changes
• System Information: Query OS, network, filesystem details
• SSH Key Management: Add, remove, list SSH authorized keys
• File Operations: Read and write files in the guest
• Extensible Design: Easy to add new QGA commands

🔧 Installation

1. Ensure you have Python 3.8+ installed
2. Virtual environment is already set up
3. Install dependencies:

   source venv/bin/activate
   pip install -r requirements.txt

💻 Usage Examples

CLI Usage

# Test connectivity
python src/qga ping

# Get OS information
python src/qga osinfo

# Execute commands
python src/qga exec ls -la /home

# Get network info
python src/qga network

# Read a file from guest
python src/qga file-read /etc/hostname

# JSON output
python src/qga -j osinfo

Python API Usage

import sys
sys.path.insert(0, 'src')
from qga_wrapper import QGAClient

# Use context manager
with QGAClient() as client:
    # Test connectivity
    if client.ping():
        print("Connected!")
    
    # Get OS info
    osinfo = client.get_osinfo()
    print(f"OS: {osinfo['name']}")
    
    # Execute command
    result = client.run_command(['uname', '-a'])
    print(result['stdout'])

🎯 Supported Operations

Information Gathering

• System info (OS, hostname, timezone)
• Network interfaces
• Filesystem information
• Logged-in users

Command Execution

• Synchronous command execution
• Asynchronous command handling
• Output capture and decoding

User & Access Management

• Password changes
• SSH key management

File Operations

• Read files from guest
• Write files to guest

System Control

• Shutdown/reboot guest

⚙️ Configuration

Default configuration is in config/config.yaml:

socket:
  path: /tmp/qga.sock
  timeout: 30

polling:
  interval: 0.1
  max_retries: 300

🔍 QEMU Setup

Ensure your QEMU VM is configured with QGA:

qemu-system-aarch64 \
  -chardev socket,path=/tmp/qga.sock,server=on,wait=off,id=qga0 \
  -device virtio-serial \
  -device virtserialport,chardev=qga0,name=org.qemu.guest_agent.0 \
  # ... other options ...

Inside the guest:

# Install and start qemu-guest-agent
sudo apt install qemu-guest-agent
sudo systemctl enable --now qemu-guest-agent

🧪 Testing

Run the example script:

source venv/bin/activate
python examples/example_usage.py

🛠️ Troubleshooting

Connection Refused:

• Ensure VM is running
• Check socket path
• Verify qemu-guest-agent is running in guest

Timeout Errors:

• Increase timeout: python src/qga -t 60 <command>
• Check guest agent status

Permission Errors:

• Check socket file permissions
• Ensure proper access rights

📦 Architecture

The wrapper uses a layered architecture:

1. QGAConnection (Low-level): Socket communication & JSON-RPC protocol
2. QGAClient (High-level): Convenient methods for QGA operations
3. CLI Interface: User-friendly command-line tool

See DEVELOPMENT.md for detailed architecture information.

🤝 Contributing

Contributions welcome! Please ensure:

• Code follows PEP 8 guidelines
• Methods include docstrings
• CLI commands have help text
• Documentation is updated

📄 License

This project is provided as-is for educational and development purposes.

📚 References

• QEMU Guest Agent Protocol
• QGA JSON Protocol Specification

---

Status: ✅ Fully functional and tested with Ubuntu 24.04 LTS guest VM