# Guest Nest

Want to see if your VMs are housing other VMs? Or how far the nesting goes? A Proxmox VM that runs on Unraid stays in Virtual Machines, and the guests inside it are listed from Unraid.

## Install

Apps (Community Applications), or Plugins → Install Plugin:

https://raw.githubusercontent.com/ibigsnet/GuestNest/main/guestnest.plg

The `testing` branch is work in progress; see [RELEASES.md](RELEASES.md).

## What it shows

| Proxmox guest | LXC page | VM page | Both |
|---|---|---|---|
| QEMU virtual machine | Under the parent row on Virtual Machines | Under the parent row on Virtual Machines | Under the parent row on Virtual Machines |
| LXC container | On the LXC page, headed "Nested on <parent VM>" | Under the parent row, marked LXC | Both of those |

Show LXC guests is on Settings → User Utilities → Guest Nest when the LXC page is available. Otherwise containers stay on the VM row, marked LXC.

The parent Unraid VM stays in whatever Folder View folder it is already in. The nested list is inside that VM's name cell, so moving or hiding the row moves or hides the list. Guest Nest does not change Folder View's order.

## How the guest list is read

Each parent VM has a **Method**:

| Method | How | Needs |
|---|---|---|
| **Guest agent** | Unraid asks the VM's QEMU guest agent to run `/usr/bin/pvesh get /cluster/resources --type vm --output-format json` inside the VM | qemu-guest-agent running in the Proxmox VM; no token, no network path to Proxmox |
| **API token** | Unraid calls `https://<proxmox>:8006/api2/json/cluster/resources?type=vm` | API token, URL, certificate choice |
| **Both** | Asks both and merges the lists by VMID (the agent's row wins). If one fails, the other is shown; if both fail, both errors are shown | Everything above |

Newly detected Proxmox VMs default to **Guest agent**. Rows saved before 2026.10.30ab keep **API token**.

### Detection

Settings → User Utilities → Guest Nest lists every Unraid VM. For each **running** VM, Guest Nest asks its guest agent `guest-ping`, then runs `/usr/bin/pveversion` inside it. The **Proxmox** column shows Detected (with the version), Not Proxmox, No guest agent, Agent: cannot check (the agent blocks guest-exec), or Not running. Detected VMs are listed first. Results are kept for 10 minutes; **Refresh** asks again. Detection only runs on the Settings page, never when the VMs page loads, so the first Settings load can take a few seconds per running VM.

### Enabling the guest agent

1. **Unraid side:** the VM needs the guest agent channel. Unraid's VM templates include it; in the VM's XML view it is:

   ```xml
   <channel type='unix'>
     <target type='virtio' name='org.qemu.guest_agent.0'/>
   </channel>
   ```

2. **Inside the Proxmox VM:** `apt install qemu-guest-agent`, then `systemctl enable --now qemu-guest-agent`.
3. **Check from Unraid:** `virsh qemu-agent-command --domain "<VM name>" '{"execute":"guest-ping"}'` prints `{"return":{}}`.
4. If the agent was started with an allow/block list (`--allow-rpcs` / `--block-rpcs`, or `/etc/default/qemu-guest-agent`), `guest-exec` and `guest-exec-status` must be allowed. Otherwise Guest Nest shows "does not allow guest-exec".

**Trust model:** guest-exec runs one fixed, read-only command (`pvesh get /cluster/resources`, or `pveversion` for detection) as root inside a VM you own. Nothing you type reaches that command line; the VM name is passed to `virsh` as its own argument. The output is treated as untrusted: at most 2 MiB, JSON only, only the vmid/name/type/status/node/template fields are kept, control characters removed, and everything is shown as text.

The VMs page does not wait on Proxmox. The list is filled after the table is drawn. A slow or offline API leaves the parent VM row as Unraid drew it and shows the error inside **Nested guests**.

## API token

On the Proxmox node: Datacenter → Permissions → Users, then API Tokens.

Use a dedicated user and a privilege-separated token that can only list guests:

1. Datacenter → Permissions → Roles → Create: `GuestNestAudit` with the single privilege `VM.Audit`.
2. Users → Add: `guestnest@pve` (Proxmox VE authentication realm; no Linux account needed).
3. API Tokens → Add: user `guestnest@pve`, token id `readonly`, **Privilege Separation checked**.
4. Permissions → Add → API Token Permission: path `/vms`, token `guestnest@pve!readonly`, role `GuestNestAudit`, Propagate on.

Token id is then `guestnest@pve!readonly`. The secret is shown once by Proxmox. Never use a `root@pam` token: Guest Nest only reads, and a leaked root token is full control of Proxmox.

## Unraid settings

Settings → User Utilities → Guest Nest. The icon is the same one VM Manager uses.

- **Show LXC guests** — LXC page, VM page, or both. Shown when the LXC page is available.
- **Proxmox VMs** — one row per Unraid VM, with the detection result. Nest **Yes** connects that VM. Nest **No** removes its saved settings and token.
- **Method** — Guest agent, API token, or Both (see above). Guest agent stores no URL or token; the API columns are only used by API token and Both.
- **API URL** — `https://` and the Proxmox port, usually `:8006`. Unraid must be able to open that address.
- **API URL** takes only `https://host` or `https://host:port`: no path, query, or fragment.
- **Token id** and **Secret**. Leave Secret blank to keep the stored one; after changing the API URL or token id the secret must be entered again.
- **Certificate**
  - **Verify** (default): normal certificate and host name checks. Use it when Proxmox has a certificate your Unraid trusts (for example ACME / Let's Encrypt).
  - **Pin on Apply**: for the certificate Proxmox generates itself. On Apply, Guest Nest reads the public key Proxmox presents and saves its SHA-256 pin; later calls are refused if the key differs. Apply from a network you trust, and compare the pin shown with `openssl x509 -in /etc/pve/local/pve-ssl.pem -pubkey -noout | openssl pkey -pubin -outform der | openssl dgst -sha256 -binary | base64` on the Proxmox node.
  - **Pin again on Apply**: after Proxmox renews its certificate.
  - There is no "don't verify" option.

Apply stores the list. Open Virtual Machines and expand **Nested guests** on that VM.

A successful call with no guests says so. While one request is asking Proxmox, other page loads get the last result instead of waiting. Create a QEMU VM or LXC on Proxmox and open the page again (the list refreshes about every 15 seconds).

## What this version does not do

It does not power guests on or off, open a console, or read Hyper-V guests inside Windows. It does not install anything on Proxmox.