hysn-firecracker-python 1.0.7__tar.gz → 1.0.8__tar.gz

{hysn_firecracker_python-1.0.7 → hysn_firecracker_python-1.0.8}/AGENTS.md

@@ -26,7 +26,7 @@ Before working on this project, ensure you have:
 - **Python 3.9+** installed
 - **KVM** enabled on your system (`lsmod | grep kvm`)
 - **Docker** installed and running
-- **Firecracker** binary in `/usr/local/bin/firecracker` or `/usr/bin/firecracker`
+- **Firecracker** binary in `/usr/local/bin/firecracker`
 - **python3-nftables** module installed
 - **uv** package manager (recommended) or pip
 
@@ -34,7 +34,7 @@ Before working on this project, ensure you have:
 
 ```bash
 # Clone the repository
-git clone https://github.com/myugan/firecracker-python.git
+git clone https://github.com/hysnsec/firecracker-python.git
 cd firecracker-python
 
 # Using uv (recommended)
@@ -204,10 +204,8 @@ Coverage reports are generated in `htmlcov/` directory when running `make test-c
 
 ### Working with Firecracker
 
-1. **Firecracker Binary Location**: The library looks for the Firecracker binary at:
-   - `/usr/local/bin/firecracker`
-   - `/usr/bin/firecracker`
-   
+1. **Firecracker Binary Location**: The library starts the binary at `MicroVMConfig.binary_path`, which is `/usr/local/bin/firecracker`. It does not search other paths.
+
    Use `firecracker-check` to verify installation.
 
 2. **KVM Access**: Ensure KVM is enabled:
@@ -229,13 +227,16 @@ Coverage reports are generated in `htmlcov/` directory when running `make test-c
 
 The project supports building rootfs from Docker images:
 
-```bash
-# Build rootfs from Docker image
-vm = MicroVM(image="ubuntu:24.04", base_rootfs="./rootfs.img")
+```python
+# Build rootfs from Docker image (run as root), then create the VM
+vm = MicroVM(image="my-rootfs:latest", base_rootfs="./rootfs.img", kernel_file="./vmlinux")
 vm.build()
+vm.create()
 ```
 
-See [`FIRECRACKER_SETUP.md`](FIRECRACKER_SETUP.md) for detailed setup instructions.
+- `create()` does not call `build()`. Call `build()` first.
+- The image must contain an init system and an SSH server. See [`docs/rootfs.md`](docs/rootfs.md).
+- For the official CI kernel and rootfs, see [`FIRECRACKER_SETUP.md`](FIRECRACKER_SETUP.md).
 
 ### Debugging
 
@@ -259,7 +260,7 @@ The default SSH user is `root`.
 
 ### Terminal Connection Timeout
 
-When spawning a terminal connection to microVMs, the default timeout is **1800000 milliseconds** (30 minutes). This timeout applies to SSH connections and can be configured when needed for long-running operations.
+When you spawn a terminal connection to a microVM from an agent tool, use a timeout of **1800000 milliseconds** (30 minutes) for long-running operations. This is guidance for the tool call. The library itself sets no SSH connection timeout.
 
 ## Security Considerations
 
@@ -312,22 +313,31 @@ firecracker-python/
 │   ├── utils.py          # Utility functions
 │   ├── exceptions.py     # Custom exceptions
 │   └── scripts.py        # CLI scripts
-├── tests/                # Test suite
-│   ├── conftest.py       # Pytest configuration
-│   └── test_microvm.py   # MicroVM tests
-├── docs/                 # Documentation
+├── tests/                # Test suite (conftest.py + test_*.py, see tests/README.md)
+├── docs/                 # Documentation (index: docs/README.md)
 │   ├── getting-started.md
+│   ├── rootfs.md
 │   ├── api-reference.md
 │   ├── configuration.md
+│   ├── network.md
+│   ├── snapshots.md
+│   ├── advanced.md
 │   ├── examples.md
-│   └── network.md
+│   ├── cleanup.md
+│   └── testing-in-docker.md
 ├── examples/             # Example scripts
+│   ├── sample.py
 │   ├── create_vm.py
+│   ├── create_vm_with_filesystem_format.py
 │   ├── configure_vm_network.py
 │   ├── load_snapshot.py
+│   ├── init              # Example init that runs MMDS user data
+│   ├── setup.sh          # Host setup for Ubuntu
 │   └── Dockerfile
+├── assets/rootfs/        # setup-firecracker-official.sh (CI kernel + rootfs)
 ├── scripts/              # Utility scripts
-│   └── run-tests-docker.sh
+│   ├── run-tests-docker.sh
+│   └── cleanup_resources.py  # Used by make cleanup-firecracker (destructive)
 ├── pyproject.toml        # Project configuration
 ├── setup.py              # Setup script
 ├── requirements.txt      # Python dependencies
@@ -409,16 +419,22 @@ See [`TODO.md`](TODO.md) for planned features:
 ```python
 from firecracker import MicroVM
 
-# Basic microVM
-vm = MicroVM()
+KERNEL = "./firecracker-files/vmlinux"
+ROOTFS = "./firecracker-files/rootfs.img"
+
+# Basic microVM (kernel_file and base_rootfs are required)
+vm = MicroVM(kernel_file=KERNEL, base_rootfs=ROOTFS)
 vm.create()
 
 # Custom configuration
-vm = MicroVM(vcpu=2, memory="4G")
+vm = MicroVM(kernel_file=KERNEL, base_rootfs=ROOTFS, vcpu=2, memory="4G")
 vm.create()
 
 # With port forwarding
-vm = MicroVM(expose_ports=True, host_port=10222, dest_port=22)
+vm = MicroVM(
+    kernel_file=KERNEL, base_rootfs=ROOTFS,
+    expose_ports=True, host_port=10222, dest_port=22,
+)
 vm.create()
 ```
 
@@ -444,9 +460,9 @@ vm.connect(key_path="/path/to/ssh/key")
 # Create snapshot
 vm.snapshot(action="create")
 
-# Load snapshot
-vm = MicroVM(kernel_file="...", rootfs_path="...")
-vm.create(snapshot=True, memory_path="...", snapshot_path="...")
+# Load snapshot (rootfs_path is a create() argument, not a constructor argument)
+vm = MicroVM(kernel_file="...", base_rootfs="...", ip_addr="<source VM IP>")
+vm.create(snapshot=True, memory_path="...", snapshot_path="...", rootfs_path="...")
 ```
 
 ## Troubleshooting

hysn_firecracker_python-1.0.8/FIRECRACKER_SETUP.md

@@ -0,0 +1,89 @@
+# Firecracker Kernel and Rootfs Setup
+
+The script `assets/rootfs/setup-firecracker-official.sh` downloads a guest kernel and an Ubuntu rootfs from the official Firecracker CI bucket. It then prepares the rootfs so that you can log in over SSH as `root`.
+
+Use this setup if you want a working kernel and rootfs pair quickly. To build a rootfs from your own Docker image instead, see [Build a rootfs from a Docker image](docs/rootfs.md).
+
+## Requirements
+
+- Linux on x86_64 or aarch64
+- `sudo` access
+- `curl`, `wget`, GNU `grep` (the script uses `grep -P`), `unsquashfs` (from `squashfs-tools`), `ssh-keygen` and `mkfs.ext4`
+- Network access to `github.com` and `s3.amazonaws.com`
+
+## Run the script
+
+Run it from any directory. The script changes to the project root first.
+
+```bash
+./assets/rootfs/setup-firecracker-official.sh
+```
+
+The script does these steps:
+
+1. Finds the latest Firecracker release and uses its CI version, for example `v1.12`.
+2. Downloads the newest guest kernel for that CI version and your CPU architecture.
+3. Downloads the newest Ubuntu squashfs rootfs for that CI version.
+4. Creates the SSH key `ssh_keys/ubuntu-22.04` if it does not exist, and adds its public key to `/root/.ssh/authorized_keys` in the rootfs.
+5. Installs `openssh-server` and a few network tools inside the rootfs with `chroot`, and allows key-based root login.
+6. Writes `nameserver 1.1.1.1` to `/etc/resolv.conf` in the rootfs.
+7. Packs the result into a 10 GB ext4 image.
+
+## Files the script creates
+
+| File | Purpose |
+|---|---|
+| `firecracker-files/vmlinux` | Guest kernel |
+| `firecracker-files/rootfs.img` | 10 GB ext4 root filesystem |
+| `ssh_keys/ubuntu-22.04` | SSH private key for `root` |
+| `ssh_keys/ubuntu-22.04.pub` | SSH public key |
+
+The key is named `ubuntu-22.04` for historical reasons. The Ubuntu version inside the rootfs depends on what the Firecracker CI bucket provides.
+
+If `firecracker-files/vmlinux` already exists, the script keeps it. It always rebuilds `rootfs.img`.
+
+## Enable IP forwarding
+
+The microVM needs IP forwarding on the host to reach the internet:
+
+```bash
+sudo sh -c "echo 1 > /proc/sys/net/ipv4/ip_forward"
+sudo iptables -P FORWARD ACCEPT
+```
+
+## Use the files with firecracker-python
+
+```python
+from firecracker import MicroVM
+
+vm = MicroVM(
+    kernel_file="./firecracker-files/vmlinux",
+    base_rootfs="./firecracker-files/rootfs.img",
+)
+vm.create()
+
+vm.connect(key_path="./ssh_keys/ubuntu-22.04")
+```
+
+You can also run the sample script, which uses the same paths:
+
+```bash
+./examples/sample.py
+```
+
+To check the files before you start a VM, run:
+
+```bash
+python3 verify-setup.py
+```
+
+## Troubleshooting
+
+- **Permission errors.** The script uses `sudo` for `chroot`, `mount` and `mkfs.ext4`. Run it as a user with `sudo` access.
+- **The script stops after a failed command.** The script uses `set -e`. On exit, it unmounts the bind mounts it created under `firecracker-files/squashfs-root`.
+- **SSH times out.** The first boot can take a minute. Check the VM log at `/var/lib/firecracker/<VM_ID>/logs/<VM_ID>.log`.
+
+## References
+
+- [Firecracker getting started guide](https://github.com/firecracker-microvm/firecracker/blob/main/docs/getting-started.md)
+- [firecracker-python getting started guide](docs/getting-started.md)

{hysn_firecracker_python-1.0.7/hysn_firecracker_python.egg-info → hysn_firecracker_python-1.0.8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hysn-firecracker-python
-Version: 1.0.7
+Version: 1.0.8
 Summary: A Python client library to interact with Firecracker microVMs
 Author: PDSO Platform
 License: MIT License
@@ -49,9 +49,9 @@ Dynamic: requires-python
 
 <p align="center">
 <a href="https://opensource.org/license/MIT"><img src="https://img.shields.io/badge/License-MIT-yellow.svg"></a>
-<a href="https://github.com/myugan/firecracker-python"><img src="https://img.shields.io/github/stars/myugan/firecracker-python.svg?style=social&label=Star"></a>
-<a href="https://github.com/myugan/firecracker-python"><img src="https://img.shields.io/github/forks/myugan/firecracker-python.svg?style=social&label=Fork"></a>
-<a href="https://github.com/myugan/firecracker-python"><img src="https://img.shields.io/github/watchers/myugan/firecracker-python.svg?style=social&label=Watch"></a>
+<a href="https://github.com/hysnsec/firecracker-python"><img src="https://img.shields.io/github/stars/hysnsec/firecracker-python.svg?style=social&label=Star"></a>
+<a href="https://github.com/hysnsec/firecracker-python"><img src="https://img.shields.io/github/forks/hysnsec/firecracker-python.svg?style=social&label=Fork"></a>
+<a href="https://github.com/hysnsec/firecracker-python"><img src="https://img.shields.io/github/watchers/hysnsec/firecracker-python.svg?style=social&label=Watch"></a>
 </p>
 
 ![Firecracker](assets/img/firecracker.png)
@@ -68,21 +68,28 @@ Some features are still being developed and will be added in the future. You can
 - [Key Features](#key-features)
 - [Getting Started](#getting-started)
 - [Usage](#usage)
+- [Documentation](#documentation)
 - [License](#license)
 - [Contributing](#contributing)
 
 ### How to Install
 
-To install from PyPI, you need to have a personal access token with read access to the repository.
+Install the package from PyPI:
 
 ```bash
-pip3 install firecracker-python
+pip3 install hysn-firecracker-python
 ```
 
-Or install from source, by cloning the repository and installing the package using pip:
+The import name is `firecracker`:
+
+```python
+from firecracker import MicroVM
+```
+
+Or install from source:
 
 ```bash
-git clone https://github.com/myugan/firecracker-python.git
+git clone https://github.com/hysnsec/firecracker-python.git
 cd firecracker-python
 
 # Using uv (recommended)
@@ -97,45 +104,49 @@ pip3 install -e .
 
 ### Key Features
 
-- Easily create microVMs with default or custom settings
-- View a list of all running microVMs
-- Access and modify microVM settings
-- Remove one or all microVMs
-- Connect to microVMs using SSH
-- Set up port forwarding in microVMs
+- Create microVMs with custom vCPU, memory and network settings
+- Build a rootfs image from a Docker image
+- List, pause, resume and delete microVMs
+- Connect to microVMs over SSH
+- Forward host ports to microVMs
+- Create and load snapshots
+- Pass metadata and user data through MMDS
+- Attach a vsock device
 
 ### Getting Started
 
 The easiest way to get started is to use the official Firecracker setup script:
 
 ```bash
-# Run the official setup script (downloads official CI kernel and rootfs)
+# Download the official CI kernel and rootfs, and create an SSH key
 ./assets/rootfs/setup-firecracker-official.sh
 
 # Then run the sample script
 ./examples/sample.py
 ```
 
-This will:
-1. Download the latest Firecracker kernel from official CI (tested with Ubuntu)
-2. Download the official Ubuntu rootfs from Firecracker CI
-3. Set up SSH keys for root access
-4. Create a properly configured ext4 rootfs image
+The setup script creates these files:
 
-The official setup uses Firecracker's CI kernel and rootfs which are **proven to work together**, avoiding kernel compatibility issues.
+| File | Purpose |
+|---|---|
+| `firecracker-files/vmlinux` | Guest kernel |
+| `firecracker-files/rootfs.img` | 10 GB ext4 rootfs with SSH enabled |
+| `ssh_keys/ubuntu-22.04` | SSH private key for `root` |
 
-**Manual Setup (Alternative):**
+The official setup uses Firecracker's CI kernel and rootfs, which are **tested together**. This avoids kernel compatibility issues. See [`FIRECRACKER_SETUP.md`](FIRECRACKER_SETUP.md) for details.
 
-If you prefer to build your own rootfs, see [`FIRECRACKER_SETUP.md`](FIRECRACKER_SETUP.md) for detailed instructions.
+To build a rootfs from your own Docker image instead, see [Build a rootfs from a Docker image](docs/rootfs.md).
 
 #### Prerequisites
 
 Before running the setup script, ensure you have:
 
-- **Firecracker binary** installed at `/usr/local/bin/firecracker` or `/usr/bin/firecracker`
-- **KVM** enabled on your system: `lsmod | grep kvm`
-- **Docker** installed and running (for rootfs setup)
-- **Python 3.9+** installed
+- **Linux** with **KVM** enabled: `lsmod | grep kvm`
+- **Firecracker binary** installed at `/usr/local/bin/firecracker`
+- **Docker** installed and running. The library connects to Docker every time you create a `MicroVM` object.
+- **Python 3.9+**
+- **python3-nftables** installed
+- **root** access. The library creates TAP devices and nftables rules.
 
 #### Enable IP Forwarding
 
@@ -154,34 +165,33 @@ source .venv/bin/activate
 ./examples/sample.py
 ```
 
-The sample script includes:
-- Automatic IP conflict detection
-- VM creation with verified files
-- SSH connection capability
-- Cleanup instructions
+The sample script:
+- Picks a free subnet so the new VM does not conflict with running VMs
+- Creates a VM with the files from the setup script
+- Offers to open an SSH session
+- Prints cleanup instructions
 
-To get started with **firecracker-python**, check out the [getting started guide](docs/getting-started.md)
+For a full walkthrough, read the [getting started guide](docs/getting-started.md).
 
 ### Usage
 
-Here are some examples of how to use the library.
+Every microVM needs a kernel (`kernel_file`) and a root filesystem (`base_rootfs`). The examples below use the files from the setup script.
 
 #### Create a microVM with custom configuration and list them all
 
 ```python
 from firecracker import MicroVM
 
-# Create a new microVM with custom configuration
-vm = MicroVM(vcpu=2, memory="4096")
-# Or
-vm = MicroVM(vcpu=2, memory="4G")
+KERNEL = "./firecracker-files/vmlinux"
+ROOTFS = "./firecracker-files/rootfs.img"
 
+# Memory accepts MiB as a number, or a string such as "4G"
+vm = MicroVM(kernel_file=KERNEL, base_rootfs=ROOTFS, vcpu=2, memory="4G")
 vm.create()
 
 # List all running microVMs
-vms = MicroVM.list()  # Static method to list all VMs
-for vm in vms:
-    print(f"VM with id {vm['id']} has IP {vm['ip_addr']} and is in state {vm['state']}")
+for info in MicroVM.list():
+    print(f"VM {info['id']} has IP {info['ip_addr']} and is {info['state']}")
 ```
 
 #### Delete a microVM by id or all microVMs
@@ -189,20 +199,21 @@ for vm in vms:
 ```python
 from firecracker import MicroVM
 
-# Create a new microVM
-vm = MicroVM()
+vm = MicroVM(kernel_file=KERNEL, base_rootfs=ROOTFS)
 vm.create()
 
 # Delete the microVM just created
 vm.delete()
 
 # Delete a specific microVM by ID
-vm.delete(id="<specific_id>")
+MicroVM().delete(id="<specific_id>")
 
 # Delete all microVMs
-vm.delete(all=True)
+MicroVM().delete(all=True)
 ```
 
+`MicroVM()` without arguments is enough to manage VMs that already exist. You only need `kernel_file` and `base_rootfs` to create a new VM.
+
 #### Enable port forwarding
 
 During initialization:
@@ -211,9 +222,14 @@ During initialization:
 from firecracker import MicroVM
 
 # Single port
-vm = MicroVM(expose_ports=True, host_port=10222, dest_port=22)
-# Multiple ports
-# vm = MicroVM(expose_ports=True, host_port=[10222, 10280], dest_port=[22, 80])
+vm = MicroVM(
+    kernel_file=KERNEL,
+    base_rootfs=ROOTFS,
+    expose_ports=True,
+    host_port=10222,
+    dest_port=22,
+)
+# Multiple ports: host_port=[10222, 10280], dest_port=[22, 80]
 
 vm.create()
 ```
@@ -221,25 +237,32 @@ vm.create()
 After creation you can also expose ports using the `port_forward` function:
 
 ```python
-from firecracker import MicroVM
-
-vm = MicroVM()
-vm.create()
-
 # Forward a single port
 vm.port_forward(host_port=10222, dest_port=22)
-# 'Port forwarding added successfully'
+# 'Port forwarding added successfully for VMM <id>'
 
 # Forward multiple ports
 vm.port_forward(host_port=[10222, 10280], dest_port=[22, 80])
-# 'Port forwarding added successfully'
 
 # Remove port forwarding
 vm.port_forward(host_port=10222, dest_port=22, remove=True)
-# 'Port forwarding removed successfully'
+# 'Port forwarding removed successfully for VMM <id>'
 ```
 
-> **Note:** When using port forwarding, you need to specify both `host_port` and `dest_port`. The number of host ports must match the number of destination ports.
+> **Note:** When using port forwarding, you need to specify both `host_port` and `dest_port`. The number of host ports must match the number of destination ports. Port forwarding supports TCP only.
+
+### Documentation
+
+- [Getting started](docs/getting-started.md)
+- [Build a rootfs from a Docker image](docs/rootfs.md)
+- [API reference](docs/api-reference.md)
+- [Configuration](docs/configuration.md)
+- [Network](docs/network.md)
+- [Snapshots](docs/snapshots.md)
+- [MMDS, vsock, overlayfs and initrd](docs/advanced.md)
+- [Examples](docs/examples.md)
+- [Cleanup](docs/cleanup.md)
+- [Testing in Docker](docs/testing-in-docker.md)
 
 ### License
 

{hysn_firecracker_python-1.0.7 → hysn_firecracker_python-1.0.8}/QUICKSTART.md

@@ -31,6 +31,14 @@ This script will:
 - Set up SSH keys for root access
 - Create a properly configured ext4 filesystem
 
+It creates these files:
+
+- `firecracker-files/vmlinux` (kernel)
+- `firecracker-files/rootfs.img` (rootfs)
+- `ssh_keys/ubuntu-22.04` (SSH private key)
+
+See [FIRECRACKER_SETUP.md](FIRECRACKER_SETUP.md) for details.
+
 ## Enable Networking
 
 Enable IP forwarding for Firecracker VMs:
@@ -68,7 +76,7 @@ python3 verify-setup.py
 ```
 
 This will check:
-- Kernel file exists and is executable
+- Kernel file exists and is readable
 - Rootfs image exists and is valid
 - SSH key files exist with correct permissions
 - System prerequisites (Firecracker, KVM, Docker, IP forwarding)
@@ -78,26 +86,15 @@ Check that your VM is running:
 ```bash
 # List all running VMs
 python3 -c "from firecracker import MicroVM; vms = MicroVM.list(); [print(f\"{v['id']}: {v['ip_addr']} ({v['state']})\") for v in vms]"
-
-# Check VM status
-./examples/sample.py | grep "VM Status"
 ```
 
 ## Connect to VM
 
-The sample script will provide instructions, or you can connect directly:
+The sample script asks if you want to connect. Answer `y` to open an SSH session.
 
-```bash
-# Using the sample script (automatic SSH connection)
-./examples/sample.py
-# Answer 'y' when prompted to connect
-
-# Or connect manually using the SSH key
-# Note: The key could be at either location depending on setup:
-#   - ssh_keys/ubuntu-22.04 (if key generated fresh)
-#   - firecracker-files/ubuntu-22.04.id_rsa (if moved by setup script)
-# Both have the same private key
+To connect yourself, use the key that the setup script created:
 
+```bash
 ssh -i ./ssh_keys/ubuntu-22.04 root@<VM_IP_ADDRESS>
 ```