# Virt Module - Rhai Examples

The Virt module provides virtualization and containerization tools for building, managing, and deploying containers, virtual machines, and filesystem layers.

## Submodules

### QCOW2 (Disk Image Management)

Create and manage QCOW2 disk images with snapshots.

#### Functions

| Function | Description |
|----------|-------------|
| `qcow2_create(path, size_gb)` | Create a new qcow2 image |
| `qcow2_info(path)` | Get image info as a map |
| `qcow2_snapshot_create(path, name)` | Create a snapshot |
| `qcow2_snapshot_delete(path, name)` | Delete a snapshot |
| `qcow2_snapshot_list(path)` | List all snapshots |
| `qcow2_build_ubuntu_24_04_base(dest, size)` | Download and prepare Ubuntu 24.04 base image |

#### Example

```rhai
// Create a 20GB disk image
qcow2_create("/tmp/disk.qcow2", 20);

// Get image info
let info = qcow2_info("/tmp/disk.qcow2");
print("Format: " + info.format);
print("Virtual size: " + info.virtual_size);

// Create and list snapshots
qcow2_snapshot_create("/tmp/disk.qcow2", "clean-install");
let snaps = qcow2_snapshot_list("/tmp/disk.qcow2");
for snap in snaps {
    print("Snapshot: " + snap.name);
}

// Build Ubuntu base image (downloads if needed)
let result = qcow2_build_ubuntu_24_04_base("/tmp/images", 30);
print("Base image: " + result.base_image_path);
```

---

### Cloud Hypervisor (VM Management)

Manage virtual machines using Cloud Hypervisor.

#### Functions

| Function | Description |
|----------|-------------|
| `cloudhv_vm_create(spec)` | Create a VM from spec map |
| `cloudhv_vm_start(id)` | Start a VM |
| `cloudhv_vm_stop(id, force)` | Stop a VM (force=true for kill) |
| `cloudhv_vm_delete(id, delete_disks)` | Delete a VM |
| `cloudhv_vm_list()` | List all VMs |
| `cloudhv_vm_info(id)` | Get VM info |

#### VM Spec Map

```rhai
let spec = #{
    id: "myvm",
    firmware_path: "/path/to/CLOUDHV.fd",  // or kernel_path for direct boot
    disk_path: "/path/to/disk.qcow2",
    vcpus: 2,
    memory_mb: 2048,
    // Optional:
    api_socket: "/tmp/myvm.sock",
    cmdline: "console=ttyS0",
    extra_args: []
};
```

#### Example

```rhai
// Create a VM
let spec = #{
    id: "ubuntu-test",
    firmware_path: "/usr/share/OVMF/CLOUDHV.fd",
    disk_path: "/tmp/images/noble-server-cloudimg-amd64.img",
    vcpus: 2,
    memory_mb: 2048
};

let vm_id = cloudhv_vm_create(spec);
print("Created VM: " + vm_id);

// Start the VM
cloudhv_vm_start(vm_id);

// List all VMs
let vms = cloudhv_vm_list();
for vm in vms {
    print("VM: " + vm.spec.id + " - " + vm.runtime.status);
}

// Get VM info
let info = cloudhv_vm_info(vm_id);
print("Status: " + info.runtime.status);
print("PID: " + info.runtime.pid);

// Stop and delete
cloudhv_vm_stop(vm_id, false);  // graceful
cloudhv_vm_delete(vm_id, false);  // keep disks
```

---

### Buildah (Container Image Building)

Build OCI/Docker container images with a fluent builder API.

#### Functions

| Function | Description |
|----------|-------------|
| `bah(name, image)` | Create a new container builder |
| `bah_new(name, image)` | Legacy: Create a Builder object |

#### Builder Methods (Chainable)

| Method | Description |
|--------|-------------|
| `.run(cmd)` | Run a command in the container |
| `.sh(cmd)` | Alias for run() |
| `.copy(src, dest)` | Copy files into the container |
| `.add(src, dest)` | Add files into the container |
| `.config(options)` | Configure container metadata |
| `.set_entrypoint(cmd)` | Set container entrypoint |
| `.entrypoint(cmd)` | Alias for set_entrypoint() |
| `.set_cmd(cmd)` | Set default command |
| `.cmd(cmd)` | Alias for set_cmd() |
| `.write_content(content, path)` | Write content to file in container |
| `.write(content, path)` | Alias for write_content() |
| `.commit(image_name)` | Commit container to image |

#### Builder Properties

| Property | Description |
|----------|-------------|
| `.container_id` | Get container ID |
| `.name` | Get container name |
| `.image` | Get base image |
| `.stdout` | Get stdout from last command |
| `.stderr` | Get stderr from last command |
| `.success` | Get success status of last command |
| `.code` | Get exit code of last command |

#### Static Functions

| Function | Description |
|----------|-------------|
| `images()` | List all images |
| `image_remove(image)` | Remove an image |
| `image_pull(image, tls_verify)` | Pull an image |
| `image_push(image, dest, tls_verify)` | Push an image |
| `image_tag(image, new_name)` | Tag an image |

---

### Nerdctl (Container Management)

Manage containers with containerd/nerdctl.

#### Container Creation

| Function | Description |
|----------|-------------|
| `nerdctl_container_new(name)` | Create a new container |
| `nerdctl_container_from_image(name, image)` | Create container from image |

#### Container Builder Methods (Chainable)

| Method | Description |
|--------|-------------|
| `.with_port(port)` | Add port mapping (e.g., "8080:80") |
| `.with_ports(array)` | Add multiple port mappings |
| `.with_volume(vol)` | Add volume mount |
| `.with_volumes(array)` | Add multiple volume mounts |
| `.with_env(key, value)` | Add environment variable |
| `.with_envs(map)` | Add multiple environment variables |
| `.with_network(network)` | Set network |
| `.with_network_alias(alias)` | Add network alias |
| `.with_cpu_limit(cpus)` | Set CPU limit |
| `.with_memory_limit(mem)` | Set memory limit |
| `.with_restart_policy(policy)` | Set restart policy |
| `.with_health_check(cmd)` | Set health check command |
| `.with_detach(bool)` | Set detach mode |
| `.build()` | Build and run the container |

#### Container Operations

| Method | Description |
|--------|-------------|
| `.start()` | Start the container |
| `.stop()` | Stop the container |
| `.remove()` | Remove the container |
| `.exec(cmd)` | Execute command in container |
| `.logs()` | Get container logs |
| `.copy(src, dest)` | Copy files to/from container |

#### Legacy Functions

| Function | Description |
|----------|-------------|
| `nerdctl_run(image)` | Run a container |
| `nerdctl_run_with_name(image, name)` | Run with name |
| `nerdctl_run_with_port(image, name, port)` | Run with port |
| `nerdctl_exec(container, cmd)` | Execute command |
| `nerdctl_stop(container)` | Stop container |
| `nerdctl_remove(container)` | Remove container |
| `nerdctl_list(all)` | List containers |
| `nerdctl_logs(container)` | Get logs |

#### Image Functions

| Function | Description |
|----------|-------------|
| `nerdctl_images()` | List images |
| `nerdctl_image_pull(image)` | Pull an image |
| `nerdctl_image_remove(image)` | Remove an image |
| `nerdctl_image_push(image, dest)` | Push an image |
| `nerdctl_image_tag(image, new_name)` | Tag an image |
| `nerdctl_image_commit(container, name)` | Commit container to image |
| `nerdctl_image_build(tag, context)` | Build image from Dockerfile |

---

### RFS (Remote Filesystem)

Mount and manage remote filesystems and pack/unpack filesystem layers.

#### Mount Functions

| Function | Description |
|----------|-------------|
| `rfs_mount(source, target, type, options)` | Mount a filesystem |
| `rfs_unmount(target)` | Unmount a filesystem |
| `rfs_list_mounts()` | List all mounts |
| `rfs_unmount_all()` | Unmount all filesystems |
| `rfs_get_mount_info(target)` | Get mount information |

#### Pack/Unpack Functions

| Function | Description |
|----------|-------------|
| `rfs_pack(dir, output, store_specs)` | Pack directory to layer |
| `rfs_unpack(input, dir)` | Unpack layer to directory |
| `rfs_list_contents(input)` | List layer contents |
| `rfs_verify(input)` | Verify layer integrity |

## Examples

See the example files in this directory:
- `01_buildah.rhai` - Container image building
- `02_nerdctl.rhai` - Container management
- `03_rfs.rhai` - Remote filesystem operations
- `04_qcow2.rhai` - QCOW2 disk image management
- `05_cloudhv.rhai` - Cloud Hypervisor VM management
