### Start VM using Propolis CLI

Source: https://github.com/oxidecomputer/propolis/blob/master/docs/server-send-vcr.md

Command to initiate the execution of a virtual machine managed by propolis-cli.

```bash
propolis-cli -s 127.0.0.1 -p 55400 state run
```

--------------------------------

### Start Propolis Server Command

Source: https://github.com/oxidecomputer/propolis/blob/master/docs/server-send-vcr.md

Command to execute the propolis-server binary with a given configuration file and listening address.

```bash
pfexec ./target/release/propolis-server run server.toml 127.0.0.1:55400
```

--------------------------------

### Build and Run RFB Example Server

Source: https://github.com/oxidecomputer/propolis/blob/master/crates/rfb/README.md

Commands to compile and execute the provided example VNC server implementation. The server listens on localhost:9000 and requires a VNC client to connect.

```bash
$ cargo build --example example-server
$ ./target/debug/examples/example-server
```

--------------------------------

### Start Propolis Server with TOML Configuration

Source: https://github.com/oxidecomputer/propolis/blob/master/docs/server-send-vcr.md

Launches the propolis-server with a specified TOML configuration file and network address. The TOML file defines paths to essential VM components like the bootrom and block device images.

```toml
bootrom = "/home/alan/vm/OVMF_CODE.fd"

[block_dev.ubuntu]
type = "file"
path = "/home/alan/vm/large-focal.raw"

[dev.block0]
driver = "pci-nvme"
block_dev = "ubuntu"
pci-path = "0.4.0"
```

--------------------------------

### Propolis Standalone TOML Configuration Example

Source: https://github.com/oxidecomputer/propolis/blob/master/bin/propolis-standalone/README.md

Example TOML configuration file for `propolis-standalone`. It defines VM parameters like name, CPUs, bootrom, memory, storage devices, and network interfaces.

```toml
[main]
name = "testvm"
cpus = 4
bootrom = "/path/to/bootrom/OVMF_CODE.fd"
memory = 1024

# Exit propolis-standalone process with <code> if instance halts (default: 0)
# exit_on_halt = <code>

# Exit propolis-standalone process with <code> if instance reboots (default: unset)
# exit_on_reboot = <code>

# Override boot order (via communication to OVMF bootrom)
# boot_order = ["net0", "block0"]

[block_dev.alpine_iso]
type = "file"
path = "/path/to/alpine-extended-3.12.0-x86_64.iso"

[dev.block0]
driver = "pci-virtio-block"
block_dev = "alpine_iso"
pci-path = "0.4.0"

[dev.net0]
driver = "pci-virtio-viona"
vnic = "vnic_name"
pci-path = "0.5.0"

```

--------------------------------

### Create and Start Crucible Downstairs Regions

Source: https://github.com/oxidecomputer/propolis/blob/master/docs/standalone-with-crucible.md

Commands to initialize and start the crucible downstairs storage regions. These commands utilize the dsc binary to manage region directories and storage parameters.

```bash
./target/release/dsc create \
  --ds-bin ./target/release/crucible-downstairs \
  --cleanup \
  --extent-size 16384 \
  --extent-count 512 \
  --block-size 4096 \
  --encrypted \
  --region-dir /pool/disk0/region \
  --region-dir /pool/disk1/region \
  --region-dir /pool/disk2/region
```

```bash
./target/release/dsc start \
  --ds-bin ./target/release/crucible-downstairs \
  --region-dir /pool/disk0/region \
  --region-dir /pool/disk1/region \
  --region-dir /pool/disk2/region
```

--------------------------------

### Propolis CPUID Profile Configuration Example

Source: https://github.com/oxidecomputer/propolis/blob/master/bin/propolis-standalone/README.md

An example TOML configuration for a custom CPUID profile, including vendor information and specific CPU leaf data.

```toml
[main]
cpuid_profile = "NAME"

[cpuid.NAME]
vendor = "amd"
"0" = [0x10, 0x68747541, 0x444d4163, 0x69746e65]
"1" = [0x830f10, 0x10800, 0xf6d83203, 0x178bfbff]
"5" = [0x0, 0x0, 0x0, 0x0]
"6" = [0x4, 0x0, 0x0, 0x0]
"7" = [0x0, 0x0, 0x0, 0x0]
"7-0" = [0x0, 0x201401a9, 0x0, 0x0]
"d" = [0x0, 0x0, 0x0, 0x0]
"d-0" = [0x7, 0x340, 0x340, 0x0]
"d-1" = [0x1, 0x0, 0x0, 0x0]
"d-2" = [0x100, 0x240, 0x0, 0x0]
"80000000" = [0x80000020, 0x68747541, 0x444d4163, 0x69746e65]
"80000001" = [0x830f10, 0x40000000, 0x444031fb, 0x25d3fbff]
"80000002" = [0x20444d41, 0x43595045, 0x38323720, 0x36312032]
"80000003" = [0x726f432d, 0x72502065, 0x7365636f, 0x20726f73]
"80000004" = [0x20202020, 0x20202020, 0x20202020, 0x202020]
"80000005" = [0xff40ff40, 0xff40ff40, 0x20080140, 0x20080140]
"80000006" = [0x48006400, 0x68006400, 0x2006140, 0x2009140]
"80000007" = [0x0, 0x0, 0x0, 0x100]
"80000008" = [0x3030, 0x7, 0x0, 0x10000]
"8000000a" = [0x1, 0x8000, 0x0, 0x13bcff]
"80000019" = [0xf040f040, 0x0, 0x0, 0x0]
"8000001a" = [0x6, 0x0, 0x0, 0x0]
"8000001b" = [0x3ff, 0x0, 0x0, 0x0]
"8000001d" = [0x0, 0x0, 0x0, 0x0]
"8000001d-0" = [0x121, 0x1c0003f, 0x3f, 0x0]
"8000001d-1" = [0x122, 0x1c0003f, 0x3f, 0x0]
"8000001d-2" = [0x143, 0x1c0003f, 0x3ff, 0x2]
"8000001d-3" = [0x163, 0x3c0003f, 0x3fff, 0x1]
"8000001f" = [0x1000f, 0x16f, 0x1fd, 0x1]

```

--------------------------------

### Start Downstairs with DSC

Source: https://github.com/oxidecomputer/propolis/blob/master/docs/server-send-vcr.md

Initiates and starts multiple downstairs instances using the 'dsc' command. Key parameters include extent size, count, block size, region count, and the path to the 'crucible-downstairs' binary. These parameters must be consistent across configuration files.

```bash
dsc start --create --cleanup --extent-size 16384 --extent-count 128 --block-size 4096 --region-count 4 --ds-bin ./target/release/crucible-downstairs
```

--------------------------------

### Propolis VM Configuration (TOML)

Source: https://github.com/oxidecomputer/propolis/blob/master/bin/propolis-cli/README.md

Example TOML file defining the configuration for a Propolis virtual machine, including block devices and network interfaces.

```toml
[block_dev.alpine_iso]
type = "file"
path = "/path/to/alpine-extended-3.12.0-x86_64.iso"

[dev.block0]
driver = "pci-virtio-block"
block_dev = "alpine_iso"
pci-path = "0.4.0"

[dev.net0]
driver = "pci-virtio-viona"
vnic = "vnic_name"
pci-path = "0.5.0"
```

--------------------------------

### Get Instance State

Source: https://context7.com/oxidecomputer/propolis/llms.txt

Retrieves the current state and properties of the VM instance, including its running state (Creating, Starting, Running, Stopping, Stopped, Rebooting, Migrating, Failed, Destroyed).

```APIDOC
## GET /instance

### Description
Retrieves the current state and properties of the VM instance, including its running state (Creating, Starting, Running, Stopping, Stopped, Rebooting, Migrating, Failed, Destroyed).

### Method
GET

### Endpoint
`/instance`

### Response
#### Success Response (200)
- **instance** (object) - Information about the VM instance.
  - **properties** (object) - Properties of the VM instance.
    - **id** (string) - Unique identifier for the VM.
    - **name** (string) - Name of the VM.
    - **description** (string) - Description of the VM.
    - **metadata** (object) - Metadata associated with the VM.
  - **state** (string) - Current state of the VM (e.g., "Running").

#### Response Example
```json
{
  "instance": {
    "properties": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "my-vm",
      "description": "Test VM instance",
      "metadata": { ... }
    },
    "state": "Running"
  }
}
```
```

--------------------------------

### Bash VNIC Setup Commands

Source: https://context7.com/oxidecomputer/propolis/llms.txt

Commands to create, manage, and delete virtual network interfaces (VNICs) on illumos systems. These VNICs are used for VM networking. Requires root privileges (pfexec).

```bash
# List available physical links
dladm show-link

# Create a VNIC on a physical interface
NIC_NAME="vnic_prop0"
NIC_MAC="02:08:20:ac:e9:16"
NIC_LINK="e1000g0"  # or your physical interface name

# Create temporary VNIC (removed on reboot)
pfexec dladm create-vnic -t -l $NIC_LINK -m $NIC_MAC $NIC_NAME

# Create persistent VNIC
pfexec dladm create-vnic -l $NIC_LINK -m $NIC_MAC $NIC_NAME

# Verify VNIC creation
dladm show-vnic $NIC_NAME

# Delete VNIC when done
pfexec dladm delete-vnic $NIC_NAME

```

--------------------------------

### Get VM Instance Specification via REST API

Source: https://context7.com/oxidecomputer/propolis/llms.txt

Retrieves the complete instance specification, including components, board settings, and current state, using a GET request to the /instance/spec endpoint. The response details the VM's configuration.

```bash
# Get the full instance specification
curl -X GET http://127.0.0.1:12400/instance/spec
```

--------------------------------

### Get Instance Spec

Source: https://context7.com/oxidecomputer/propolis/llms.txt

Retrieves the complete instance specification including all configured components, board settings, and current state.

```APIDOC
## GET /instance/spec

### Description
Retrieves the complete instance specification including all configured components, board settings, and current state.

### Method
GET

### Endpoint
`/instance/spec`

### Response
#### Success Response (200)
- **properties** (object) - Properties of the VM instance.
- **state** (string) - Current state of the VM.
- **spec** (object) - The VM specification.
  - **type** (string) - Type of the spec (e.g., "Present").
  - **value** (object) - The actual specification values.
    - **board** (object) - Board configuration.
      - **chipset** (object) - Chipset configuration.
        - **type** (string) - Chipset type.
        - **value** (object) - Chipset specific values.
      - **cpus** (integer) - Number of CPUs.
      - **memory_mb** (integer) - Memory in MB.
    - **components** (object) - VM components.

#### Response Example
```json
{
  "properties": { ... },
  "state": "Running",
  "spec": {
    "type": "Present",
    "value": {
      "board": {
        "chipset": { "type": "i440_fx", "value": { "enable_pcie": false } },
        "cpus": 4,
        "memory_mb": 4096
      },
      "components": { ... }
    }
  }
}
```
```

--------------------------------

### Cloud-Init Configuration for VM Provisioning (TOML)

Source: https://context7.com/oxidecomputer/propolis/llms.txt

TOML configuration for integrating cloud-init into a VM for automated provisioning. It defines VM settings and a cloud-init block device backend, including inline user-data with user accounts, package installations, and run commands.

```toml
# cloudinit-config.toml

[main]
name = "cloudinit-vm"
cpus = 2
bootrom = "/path/to/OVMF_CODE.fd"
memory = 2048

# Boot disk
[block_dev.boot_disk]
type = "file"
path = "/path/to/cloud-image.raw"

[dev.block0]
driver = "pci-virtio-block"
block_dev = "boot_disk"
pci-path = "0.4.0"

# Cloud-init disk device
[dev.cloudinit]
driver = "pci-virtio-block"
pci-path = "0.16.0"
block_dev = "cloudinit_be"

# Cloud-init backend (NoCloud format)
[block_dev.cloudinit_be]
type = "cloudinit"

# Cloud-init configuration
[cloudinit]
user-data = '''
#cloud-config
users:
  - default
  - name: admin
    sudo: 'ALL=(ALL) NOPASSWD:ALL'
    lock_passwd: false
    # Password: "changeme" (use mkpasswd to generate)
    hashed_passwd: '$6$rounds=4096$salt$hashedpassword'
    ssh_authorized_keys:
      - ssh-rsa AAAAB3... user@host

package_update: true
packages:
  - htop
  - vim

runcmd:
  - echo "Hello from cloud-init" > /etc/motd
'''

# Alternative: Load from files
# user-data-path = "/path/to/user-data.yaml"
# meta-data = "instance-id: my-instance\nlocal-hostname: my-vm"
# meta-data-path = "/path/to/meta-data.yaml"
# network-config-path = "/path/to/network-config.yaml"

```

--------------------------------

### Create VM with Crucible Disk using Propolis CLI

Source: https://github.com/oxidecomputer/propolis/blob/master/docs/server-send-vcr.md

Command to create a new virtual machine and attach a Crucible disk using the propolis-cli. It requires the server address, port, and a JSON file detailing the Crucible disk configuration.

```bash
propolis-cli -s 127.0.0.1 -p 55400 new crub --crucible-disks crucible-disks.json
```

--------------------------------

### Get VM Instance State via REST API

Source: https://context7.com/oxidecomputer/propolis/llms.txt

Retrieves the current state and properties of a VM instance using a GET request to the /instance endpoint. The response includes the instance's ID, name, description, metadata, and current running state.

```bash
# Get current instance state and properties
curl -X GET http://127.0.0.1:12400/instance
```

--------------------------------

### Basic Standalone VM Configuration (TOML)

Source: https://context7.com/oxidecomputer/propolis/llms.txt

TOML configuration for running a standalone virtual machine directly from a configuration file. It specifies VM resources, boot options, and block device backends for a boot disk and an installation ISO.

```toml
# standalone-config.toml

[main]
name = "standalone-vm"
cpus = 4
bootrom = "/path/to/OVMF_CODE.fd"
memory = 2048

# Exit with code 0 when guest halts
exit_on_halt = 0

# Exit with code 1 when guest reboots (optional)
# exit_on_reboot = 1

# Boot order (optional)
boot_order = ["block0", "net0"]

# Block device backend
[block_dev.boot_disk]
type = "file"
path = "/path/to/disk.raw"

# ISO image backend
[block_dev.install_iso]
type = "file"
path = "/path/to/alpine-extended-3.18.0-x86_64.iso"

# Boot disk device
[dev.block0]
driver = "pci-virtio-block"
block_dev = "boot_disk"
pci-path = "0.4.0"

# CD-ROM device
[dev.cdrom]
driver = "pci-virtio-block"
block_dev = "install_iso"
pci-path = "0.5.0"

# Network interface
[dev.net0]
driver = "pci-virtio-viona"
vnic = "vnic_prop0"
pci-path = "0.6.0"

```

--------------------------------

### Propolis Standalone Crucible Storage Configuration

Source: https://github.com/oxidecomputer/propolis/blob/master/bin/propolis-standalone/README.md

Example TOML configuration for `propolis-standalone` using Crucible-backed storage. This section details required options for connecting to a Downstairs datastore and managing generations.

```toml
[block_dev.some_datastore]
type = "crucible"

# === REQUIRED OPTIONS ===
# these MUST match the region configuration downstairs
block_size = 512
blocks_per_extent = 262144
extent_count = 32

# Array of the SocketAddrs of the Downstairs instances. There must be three

```

--------------------------------

### Create Crucible Disk Configuration (JSON)

Source: https://github.com/oxidecomputer/propolis/blob/master/docs/server-send-vcr.md

Defines the configuration for a new Crucible NVMe disk, including device type, name, slot, and volume construction details. Crucially, parameters like block size, extent size, and extent count must match those used in the 'dsc' command.

```json
[
{
    "device": "nvme",
    "name": "block2",
    "read_only": false,
    "slot": 3,
    "volume_construction_request": {
        "type": "volume",
        "block_size": 4096,
        "id": "0cedae45-3d6e-4d90-b2cb-56f1a1a42a89",
        "read_only_parent": null,
        "sub_volumes": [
            {
                "type": "region",
                "block_size": 4096,
                "blocks_per_extent": 16384,
                "extent_count": 128,
                "gen": 1,
                "opts": {
                    "cert_pem": null,
                    "control": null,
                    "flush_timeout": null,
                    "id": "0cedae45-3d6e-4d90-b2cb-56f1a1a42a89",
                    "key": null,
                    "key_pem": null,
                    "lossy": false,
                    "read_only": false,
                    "root_cert_pem": null,
                    "target": ["127.0.0.1:8810",
                             "127.0.0.1:8820",
                             "127.0.0.1:8830"
                    ]
                }
            }
        ]
    }
}
]
```

--------------------------------

### Replace Downstairs using Propolis CLI

Source: https://github.com/oxidecomputer/propolis/blob/master/docs/server-send-vcr.md

Command to initiate the replacement of a downstairs using the propolis-cli. It requires the server address, port, the VM instance ID, and a JSON file containing the VCR replacement configuration.

```bash
propolis-cli -s 127.0.0.1 -p 55400 vcr -u 0cedae45-3d6e-4d90-b2cb-56f1a1a42a89 --vcr-replace ./replace.json
```

--------------------------------

### Configure and Run Propolis Standalone

Source: https://github.com/oxidecomputer/propolis/blob/master/docs/standalone-with-crucible.md

Provides a sample TOML configuration for propolis-standalone, defining VM resources and block device settings. Includes the command to launch the standalone instance with the configuration file.

```toml
[main]
name = "testvm"
cpus = 4
bootrom = "/tmp/OVMF_CODE.fd"
memory = 2048

[block_dev.ubuntu]
type = "file"
path = "/tmp/large-focal.raw"

[dev.block0]
driver = "pci-nvme"
block_dev = "ubuntu"
pci-path = "0.4.0"

[block_dev.my_crucible]
type = "crucible"
block_size = 4096
blocks_per_extent = 131072
extent_count = 128
targets = [
  "127.0.0.1:8810",
  "127.0.0.1:8820",
  "127.0.0.1:8830",
]
generation = 5
upstairs_id = "e4396bd0-ede1-48d7-ac14-3d2094dfba5b"
encryption_key = "tCw7zw0hAsPuxMOTWwnPEFYjBK9qJRtYyGdEXKEnrg0="

[dev.block1]
driver = "pci-nvme"
block_dev = "my_crucible"
pci-path = "0.5.0"

[dev.net0]
driver = "pci-virtio-viona"
vnic = "vnic_prop0"
pci-path = "0.6.0"
```

```bash
propolis-standalone standalone.toml
```

--------------------------------

### Propolis CLI: Create VM with Crucible Disks

Source: https://github.com/oxidecomputer/propolis/blob/master/docs/migrate-with-crucible.md

Shows the command to create a new virtual machine using the propolis-cli, specifying Crucible disks via a JSON file. The `--crucible-disks` flag points to the JSON file containing disk requests, and `vm0` is the name of the VM being created.

```bash
$ ./target/debug/propolis-cli -s 172.20.3.73 -p 8000 new --crucible-disks disks.json vm0
```

--------------------------------

### Propolis CLI: Run VM

Source: https://github.com/oxidecomputer/propolis/blob/master/docs/migrate-with-crucible.md

A simple command to run a virtual machine that has been previously created or migrated using Propolis. This command initiates the VM's execution.

```bash
$ ./target/debug/propolis-cli -s 172.20.3.73 -p 8000 state run
```

--------------------------------

### Propolis CLI: Migrate VM with Crucible Disks

Source: https://github.com/oxidecomputer/propolis/blob/master/docs/migrate-with-crucible.md

Illustrates the command for migrating a virtual machine to a destination server using Propolis. It requires specifying the destination server's address and port, and uses the `--crucible-disks` flag with an updated JSON file (with incremented generation number) for the destination.

```bash
$ ./target/debug/propolis-cli -s 172.20.3.73 -p 8000 migrate 172.20.3.71 -p 8000 --crucible-disks disks2.json
```

--------------------------------

### Create and Manage VM Instances with Rust Client

Source: https://context7.com/oxidecomputer/propolis/llms.txt

Demonstrates the use of the propolis-client library to define an InstanceSpec, configure virtual hardware components like Virtio disks and serial ports, and manage the VM lifecycle through state requests and monitoring.

```rust
use propolis_client::{Client, types::*};
use propolis_client::instance_spec::*;
use std::collections::BTreeMap;
use uuid::Uuid;

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let client = Client::new("http://127.0.0.1:12400");

    let mut components = BTreeMap::new();

    components.insert(
        SpecKey::Name("boot-disk".to_string()),
        ComponentV0::VirtioDisk(VirtioDisk {
            backend_id: SpecKey::Name("boot-backend".to_string()),
            pci_path: PciPath::new(0, 4, 0)?,
        }),
    );

    components.insert(
        SpecKey::Name("boot-backend".to_string()),
        ComponentV0::FileStorageBackend(FileStorageBackend {
            path: "/path/to/disk.raw".to_string(),
            readonly: false,
            block_size: 512,
            workers: None,
        }),
    );

    let spec = InstanceSpec {
        board: Board {
            chipset: Chipset::I440Fx(I440Fx { enable_pcie: false }),
            cpus: 4,
            memory_mb: 4096,
            cpuid: None,
            guest_hv_interface: GuestHypervisorInterface::Bhyve,
        },
        components,
        smbios: None,
    };

    let request = InstanceEnsureRequest {
        properties: InstanceProperties { /* ... */ },
        init: InstanceInitializationMethod::Spec { spec },
    };

    client.instance_ensure().body(request).send().await?;
    client.instance_state_put().body(InstanceStateRequested::Run).send().await?;

    Ok(())
}
```

--------------------------------

### Propolis CLI VM Management Commands

Source: https://github.com/oxidecomputer/propolis/blob/master/bin/propolis-cli/README.md

Commands to create, run, and connect to a Propolis VM using the propolis-cli. Requires server IP, port, and a configuration file.

```bash
# propolis-cli -s <server ip> -p <port> new --config-toml <path> <VM name>
# propolis-cli -s <server ip> -p <port> state run
# propolis-cli -s <server ip> -p <port> serial
```

--------------------------------

### Configure Cloud-Init Disk and Backend in TOML

Source: https://github.com/oxidecomputer/propolis/blob/master/bin/propolis-standalone/README.md

This configuration defines a virtio-block device and a corresponding cloudinit backend for Propolis. It demonstrates how to inject user-data directly into the configuration using cloud-config syntax.

```toml
[dev.cloudinit]
driver = "pci-virtio-block"
pci-path = "0.16.0"
block_dev = "cloudinit_be"

[block_dev.cloudinit_be]
type = "cloudinit"

[cloudinit]
user-data = '''
#cloud-config
users:
- default
- name: test
  sudo: 'ALL=(ALL) NOPASSWD:ALL'
  lock_passwd: false
  hashed_passwd: '$6$rounds=4096$MBW/3OrwWLifnv30$QM.oCQ3pzV7X4EToX9IyZmplvaTgpZ6YJ50MhQrwlryj1soqBW5zvraVttYwfyWdxigHpZHTjY9kT.029UOEn1'
'''
```

--------------------------------

### GET /instance/migration-status

Source: https://context7.com/oxidecomputer/propolis/llms.txt

Retrieves the current status of inbound or outbound migrations for the instance.

```APIDOC
## GET /instance/migration-status

### Description
Retrieves the status of any active or completed migrations for the instance, including both inbound and outbound migrations.

### Method
GET

### Endpoint
/instance/migration-status

### Response
#### Success Response (200)
- **migration_in** (object|null) - Details of inbound migration if active.
- **migration_out** (object|null) - Details of outbound migration if active.

#### Response Example
{
  "migration_in": null,
  "migration_out": {
    "id": "550e8400-e29b-41d4-a716-446655440099",
    "state": "RamPush"
  }
}
```

--------------------------------

### GET /instance/serial/history

Source: https://context7.com/oxidecomputer/propolis/llms.txt

Retrieves buffered serial console output from the instance, supporting byte offsets or recent byte counts.

```APIDOC
## GET /instance/serial/history

### Description
Retrieves buffered serial console output from the instance. Supports reading from a specific byte offset or from the most recent N bytes.

### Method
GET

### Endpoint
/instance/serial/history

### Parameters
#### Query Parameters
- **most_recent** (integer) - Optional - Number of bytes to retrieve from the end of the buffer.
- **from_start** (integer) - Optional - Byte offset to start reading from.
- **max_bytes** (integer) - Optional - Maximum number of bytes to return.

### Request Example
GET /instance/serial/history?most_recent=4096

### Response
#### Success Response (200)
- **data** (array) - Array of byte values.
- **last_byte_offset** (integer) - The ending offset of the returned data.

#### Response Example
{
  "data": [72, 101, 108, 108, 111],
  "last_byte_offset": 5096
}
```

--------------------------------

### POST /instance/disk/{id}/vcr

Source: https://github.com/oxidecomputer/propolis/blob/master/docs/server-send-vcr.md

Replaces a downstairs instance of a Crucible volume attached to a Propolis instance by providing an updated Volume Construction Request (VCR).

```APIDOC
## POST /instance/disk/{id}/vcr

### Description
Updates the configuration of a specific Crucible volume by submitting a new Volume Construction Request (VCR). This is typically used to replace a downstairs instance by incrementing the generation number and updating the target list.

### Method
POST

### Endpoint
/instance/disk/{id}/vcr

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier (UUID) of the Crucible volume.

#### Request Body
- **name** (string) - Required - The name of the block device.
- **vcr_json** (string) - Required - A JSON-encoded string representing the updated Volume Construction Request. Note: The internal JSON must be escaped (e.g., \" for quotes) and provided as a single line.

### Request Example
{
  "name": "block2",
  "vcr_json": "{ \"type\": \"volume\", \"block_size\": 4096, \"id\": \"0cedae45-3d6e-4d90-b2cb-56f1a1a42a89\", \"sub_volumes\": [ { \"gen\": 7, \"opts\": { \"target\": [\"127.0.0.1:8810\", \"127.0.0.1:8820\", \"127.0.0.1:8840\"] } } ] }"
}

### Response
#### Success Response (200)
- **status** (string) - Confirmation of the VCR update process initiation.

#### Response Example
{
  "status": "success"
}
```

--------------------------------

### Run Propolis Standalone Binary

Source: https://github.com/oxidecomputer/propolis/blob/master/bin/propolis-standalone/README.md

Command to execute the propolis-standalone binary with a TOML configuration file. This binary is used for quick VM prototyping.

```bash
pfexec propolis-standalone <config_file>
```

--------------------------------

### POST /instance/disk/{disk_id}/snapshot/{snapshot_id}

Source: https://context7.com/oxidecomputer/propolis/llms.txt

Requests a point-in-time disk snapshot for a Crucible storage backend.

```APIDOC
## POST /instance/disk/{disk_id}/snapshot/{snapshot_id}

### Description
Issues a snapshot request to a Crucible storage backend for point-in-time disk snapshots.

### Method
POST

### Endpoint
/instance/disk/{disk_id}/snapshot/{snapshot_id}

### Parameters
#### Path Parameters
- **disk_id** (string) - Required - The identifier of the disk.
- **snapshot_id** (string) - Required - The unique identifier for the snapshot request.

### Response
#### Success Response (200)
- **null** - Returns null on success.
```

--------------------------------

### Propolis CLI: View VM Serial Console

Source: https://github.com/oxidecomputer/propolis/blob/master/docs/migrate-with-crucible.md

Command to access the serial console output of a running virtual machine managed by Propolis. This is useful for monitoring the VM's boot process and debugging.

```bash
$ ./target/debug/propolis-cli -s 172.20.3.73 -p 8000 serial
```

--------------------------------

### Run and Connect to Standalone VM (Bash)

Source: https://context7.com/oxidecomputer/propolis/llms.txt

Bash commands to execute a standalone Propolis VM using its TOML configuration and to connect to its serial console for interaction. The VM waits for a serial console connection before booting.

```bash
# Run standalone VM
pfexec ./target/release/propolis-standalone standalone-config.toml

# Connect to serial console (VM waits for connection before booting)
# Using sercons or screen
sercons ./ttya
# or
screen ./ttya

```

--------------------------------

### VCR Replace JSON Configuration

Source: https://github.com/oxidecomputer/propolis/blob/master/docs/server-send-vcr.md

JSON payload used to replace a downstairs. It includes the disk name and a stringified VCR JSON. The VCR JSON must have an incremented generation number and one modified target IP:Port compared to the original.

```json
{
    "name": "block2",
    "vcr_json": "{ \"type\": \"volume\", \"block_size\": 4096, \"id\": \"0cedae45-3d6e-4d90-b2cb-56f1a1a42a89\", \"read_only_parent\": null, \"sub_volumes\": [ { \"type\": \"region\", \"block_size\": 4096, \"blocks_per_extent\": 16384, \"extent_count\": 128, \"gen\": 7, \"opts\": { \"cert_pem\": null, \"control\": null, \"flush_timeout\": null, \"id\": \"0cedae45-3d6e-4d90-b2cb-56f1a1a42a89\", \"key\": null, \"key_pem\": null, \"lossy\": false, \"read_only\": false, \"root_cert_pem\": null, \"target\": [\"127.0.0.1:8810\", \"127.0.0.1:8820\", \"127.0.0.1:8840\" ] } } ] }"
}
```

--------------------------------

### Create VM Instance via REST API

Source: https://context7.com/oxidecomputer/propolis/llms.txt

Creates a new VM instance using a PUT request to the /instance endpoint. Requires a JSON payload defining instance properties and initialization specifications. The response indicates the migration status.

```bash
# Create a new VM instance via REST API
curl -X PUT http://127.0.0.1:12400/instance \
  -H "Content-Type: application/json" \
  -d '{
    "properties": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "my-vm",
      "description": "Test VM instance",
      "metadata": {
        "project_id": "550e8400-e29b-41d4-a716-446655440001",
        "silo_id": "550e8400-e29b-41d4-a716-446655440002",
        "sled_id": "550e8400-e29b-41d4-a716-446655440003",
        "sled_model": "gimlet",
        "sled_revision": 1,
        "sled_serial": "BRM12345678"
      }
    },
    "init": {
      "method": "Spec",
      "value": {
        "spec": {
          "board": {
            "chipset": { "type": "i440_fx", "value": { "enable_pcie": false } },
            "cpus": 4,
            "memory_mb": 4096
          },
          "components": {
            "boot-disk": {
              "type": "virtio_disk",
              "component": {
                "backend_id": "boot-disk-backend",
                "pci_path": { "bus": 0, "device": 4, "function": 0 }
              }
            },
            "boot-disk-backend": {
              "type": "file_storage_backend",
              "component": {
                "path": "/path/to/disk.raw",
                "readonly": false,
                "block_size": 512
              }
            },
            "com1": {
              "type": "serial_port",
              "component": { "num": "com1" }
            }
          }
        }
      }
    }
  }'
```

--------------------------------

### Monitor VM Instance State Changes via REST API

Source: https://context7.com/oxidecomputer/propolis/llms.txt

Long-polls for VM instance state changes using a GET request to the /instance/state-monitor endpoint. Requires a JSON payload with a generation number; the server responds when the state differs from the specified generation.

```bash
# Monitor state changes (blocks until state changes from gen 0)
curl -X GET http://127.0.0.1:12400/instance/state-monitor \
  -H "Content-Type: application/json" \
  -d '{"gen": 0}'
```

--------------------------------

### Create/Ensure VM Instance

Source: https://context7.com/oxidecomputer/propolis/llms.txt

Creates a new VM instance with the specified configuration and properties. The instance spec defines the virtual hardware including CPUs, memory, storage backends, and network interfaces.

```APIDOC
## PUT /instance

### Description
Creates a new VM instance with the specified configuration and properties. The instance spec defines the virtual hardware including CPUs, memory, storage backends, and network interfaces.

### Method
PUT

### Endpoint
`/instance`

### Parameters
#### Request Body
- **properties** (object) - Required - Properties of the VM instance.
  - **id** (string) - Required - Unique identifier for the VM.
  - **name** (string) - Required - Name of the VM.
  - **description** (string) - Optional - Description of the VM.
  - **metadata** (object) - Optional - Metadata associated with the VM.
    - **project_id** (string) - Required - Project ID.
    - **silo_id** (string) - Required - Silo ID.
    - **sled_id** (string) - Required - Sled ID.
    - **sled_model** (string) - Required - Sled model.
    - **sled_revision** (integer) - Required - Sled revision.
    - **sled_serial** (string) - Required - Sled serial number.
- **init** (object) - Required - Initialization configuration for the VM.
  - **method** (string) - Required - Initialization method (e.g., "Spec").
  - **value** (object) - Required - Initialization value.
    - **spec** (object) - Required - VM specification.
      - **board** (object) - Required - Board configuration.
        - **chipset** (object) - Required - Chipset configuration.
          - **type** (string) - Required - Chipset type (e.g., "i440_fx").
          - **value** (object) - Required - Chipset specific values.
            - **enable_pcie** (boolean) - Optional - Enable PCIe.
        - **cpus** (integer) - Required - Number of CPUs.
        - **memory_mb** (integer) - Required - Memory in MB.
      - **components** (object) - Required - VM components.
        - **boot-disk** (object) - Required - Boot disk configuration.
          - **type** (string) - Required - Component type (e.g., "virtio_disk").
          - **component** (object) - Required - Component specific configuration.
            - **backend_id** (string) - Required - Backend ID for the disk.
            - **pci_path** (object) - Required - PCI path for the device.
              - **bus** (integer) - Required - PCI bus number.
              - **device** (integer) - Required - PCI device number.
              - **function** (integer) - Required - PCI function number.
        - **boot-disk-backend** (object) - Required - Boot disk storage backend.
          - **type** (string) - Required - Backend type (e.g., "file_storage_backend").
          - **component** (object) - Required - Backend specific configuration.
            - **path** (string) - Required - Path to the disk image.
            - **readonly** (boolean) - Optional - Read-only flag.
            - **block_size** (integer) - Optional - Block size.
        - **com1** (object) - Required - Serial port configuration.
          - **type** (string) - Required - Component type (e.g., "serial_port").
          - **component** (object) - Required - Component specific configuration.
            - **num** (string) - Required - Serial port number (e.g., "com1").

### Request Example
```json
{
  "properties": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "my-vm",
    "description": "Test VM instance",
    "metadata": {
      "project_id": "550e8400-e29b-41d4-a716-446655440001",
      "silo_id": "550e8400-e29b-41d4-a716-446655440002",
      "sled_id": "550e8400-e29b-41d4-a716-446655440003",
      "sled_model": "gimlet",
      "sled_revision": 1,
      "sled_serial": "BRM12345678"
    }
  },
  "init": {
    "method": "Spec",
    "value": {
      "spec": {
        "board": {
          "chipset": { "type": "i440_fx", "value": { "enable_pcie": false } },
          "cpus": 4,
          "memory_mb": 4096
        },
        "components": {
          "boot-disk": {
            "type": "virtio_disk",
            "component": {
              "backend_id": "boot-disk-backend",
              "pci_path": { "bus": 0, "device": 4, "function": 0 }
            }
          },
          "boot-disk-backend": {
            "type": "file_storage_backend",
            "component": {
              "path": "/path/to/disk.raw",
              "readonly": false,
              "block_size": 512
            }
          },
          "com1": {
            "type": "serial_port",
            "component": { "num": "com1" }
          }
        }
      }
    }
  }
}
```

### Response
#### Success Response (200)
- **migrate** (null) - Indicates if migration is in progress.

#### Response Example
```json
{
  "migrate": null
}
```
```

--------------------------------

### Migrate VM with Crucible Disk Backend Updates

Source: https://context7.com/oxidecomputer/propolis/llms.txt

Command to migrate a VM using the propolis-cli, specifically updating the Crucible disk backend by incrementing the generation number. This ensures data consistency during migration.

```bash
propolis-cli -s 172.20.3.73 -p 12400 migrate 172.20.3.71 -p 12400 \
  --crucible-disks disks-updated.json
```

--------------------------------

### Create a Virtual Network Interface (VNIC)

Source: https://github.com/oxidecomputer/propolis/blob/master/bin/propolis-standalone/README.md

Bash script to create a VNIC using `dladm`. This is necessary for network connectivity in the VM. It checks if the VNIC already exists before creating it.

```bash
NIC_NAME="vnic_prop0"
NIC_MAC="02:08:20:ac:e9:16"
NIC_LINK="e1000g0"

if ! dladm show-vnic $NIC_NAME 2> /dev/null;
then
  dladm create-vnic -t -l $NIC_LINK -m $NIC_MAC $NIC_NAME
fi

```

--------------------------------

### Crucible Storage Backend Configuration (TOML)

Source: https://context7.com/oxidecomputer/propolis/llms.txt

TOML configuration for setting up a Crucible distributed storage system as a block device backend for a VM. This is suitable for production environments and requires specifying target addresses and a generation number.

```toml
# crucible-config.toml

[main]
name = "crucible-vm"
cpus = 4
bootrom = "/path/to/OVMF_CODE.fd"
memory = 4096

# Crucible-backed storage
[block_dev.crucible_disk]
type = "crucible"

# These must match the downstairs region configuration
block_size = 512
blocks_per_extent = 262144
extent_count = 32

# Downstairs addresses (exactly 3 required)
targets = [
  "172.20.3.73:8810",
  "172.20.3.73:8820",
  "172.20.3.73:8830",
]

# Generation number - must increment with each VM start/migration
generation = 1

# Optional: UUID for the upstairs
# upstairs_id = "e4396bd0-ede1-48d7-ac14-3d2094dfba5b"

# Optional: Enable synthetic failures for testing
# lossy = false

# Optional: Flush timeout in seconds (default: 5)
# flush_timeout = 5

# Optional: Base64-encoded 256-bit encryption key
# encryption_key = "base64_encoded_key_here"

# Optional: TLS certificates
# cert_pem = "/path/to/cert.pem"
# key_pem = "/path/to/key.pem"
# root_cert_pem = "/path/to/root.pem"

# Optional: Control interface for snapshots
# control_addr = "127.0.0.1:9000"

# Optional: Read-only mode
# read_only = false

[dev.block0]
driver = "pci-virtio-block"
block_dev = "crucible_disk"
pci-path = "0.4.0"

```

--------------------------------

### Configure local artifacts in TOML

Source: https://github.com/oxidecomputer/propolis/blob/master/phd-tests/README.md

Defines a local artifact configuration for the Propolis server. This allows for frequent builds without requiring manual SHA256 digest updates.

```toml
[artifacts.propolis]
filename = "propolis-server"
kind = "propolis_server"

[artifacts.propolis.source.local_path]
path = "/home/oxide/propolis/target/debug"
```