## Keyboard shortcuts

Press `←` or `→` to navigate between chapters

Press `S` or `/` to search in the book

Press `?` to show this help

Press `Esc` to hide this help

# Cloud-Init and SSH Keys

vmctl uses cloud-init to configure guests on first boot. It generates a NoCloud seed ISO containing user-data and meta-data, which the guest's cloud-init agent picks up automatically.

## SSH Key Modes

There are three ways to get SSH access to a VM:

### 1. Auto-Generated Keypair (Recommended)

When you define a `cloud-init` block without an explicit `ssh-key`, vmctl generates a per-VM Ed25519 keypair:

    cloud-init {
        hostname "myvm"
    }

    ssh {
        user "ubuntu"
    }

The keys are stored in the VM's work directory:

- `~/.local/share/vmctl/vms/<name>/id_ed25519_generated` (private)
- `~/.local/share/vmctl/vms/<name>/id_ed25519_generated.pub` (public)

This is the simplest option. No key management required.

### 2. Explicit SSH Key

Point to your own public key file:

    cloud-init {
        ssh-key "~/.ssh/id_ed25519.pub"
    }

    ssh {
        user "ubuntu"
        private-key "~/.ssh/id_ed25519"
    }

### 3. Raw User-Data

Provide a complete cloud-config YAML file for full control:

    cloud-init {
        user-data "./my-cloud-config.yaml"
    }

In this mode, you're responsible for setting up SSH access yourself in the user-data.

## SSH Key Resolution

When vmctl needs to SSH into a VM (for `vmctl ssh` or provisioning), it searches for a private key in this order:

1. Generated key in the VM's work directory (`id_ed25519_generated`)
2. Key specified with `--key` flag or `private-key` in VMFile ssh block
3. Standard keys in `~/.ssh/`: `id_ed25519`, `id_ecdsa`, `id_rsa`

## SSH User Resolution

1. `--user` CLI flag
2. `user` in VMFile `ssh` block
3. Default: `"vm"`

## Cloud-Init User Setup

When vmctl generates the cloud-config, it creates a user with:

- The specified username
- Passwordless `sudo` access
- The SSH public key in `authorized_keys`
- Bash as the default shell
- Root login disabled