feat: add --user/--password flags for cloudimg credential injection

- Replace global --root-password with per-VM --user/--password flags
  (defaults: root/cocoon). Credentials are transient (json:"-") and
  never persisted in the VM record.
- Non-root users are created via cloud-init runcmd (useradd + chpasswd
  + NOPASSWD sudoers). Root stays locked when a custom user is set.
- Validate username (Linux format) and reject shell-unsafe passwords.
- OCI Dockerfiles: add cocoon.ssh.username/password LABELs.
- Remove DefaultRootPassword from global config.

Author: CMGS

KNOWN_ISSUES.md

@@ -27,6 +27,27 @@ OCI VMs use the kernel `ip=` boot parameter for network configuration. While mul
 
 **Workaround**: the post-clone setup hints write persistent MAC-based systemd-networkd configs for **all** NICs. These survive reboots and correctly configure every interface regardless of the kernel `ip=` limitation.
 
+## Non-root user creation requires cloud-init final stage
+
+When `--user` specifies a non-root username (e.g. `--user admin`), the user is created via cloud-init `runcmd` which runs in the **final stage** — after networking, SSH key generation, and other modules. This means:
+
+- The user does not exist until cloud-init fully completes (typically 20-30s after boot)
+- SSH login as the custom user will fail if attempted before cloud-init finishes
+- `cloud-init status` shows `done` when the user is ready
+
+The root user's password is set via `chpasswd` (config stage, earlier) and is available sooner, but `--user admin` deliberately does not set a root password — root stays locked for security.
+
+**Workaround**: wait for `cloud-init status: done` before attempting SSH. The default `root`/`cocoon` credentials use the faster `chpasswd` path and are available immediately after SSH starts.
+
+## Clone preserves guest credentials from snapshot
+
+Clone regenerates cidata for **network reconfiguration only** — it does not inject new user or password settings. The cloned VM's credentials are whatever the source VM had in `/etc/shadow` at snapshot time.
+
+- `--user`/`--password` flags are not available on `cocoon vm clone`
+- If you need different credentials, change them inside the guest after boot
+
+This is by design: clone restores the VM's exact state including all account settings.
+
 ## Clone/restore disk queue count is immutable
 
 When cloning or restoring a VM with a different `--cpu` value, the disk `num_queues` (one queue per vCPU) retains the snapshot's original value. This is because `num_queues` is part of the virtio-blk device state baked into the binary snapshot — changing it in `config.json` causes Cloud Hypervisor to crash on `vm.restore`.

README.md

@@ -13,7 +13,7 @@ Lightweight MicroVM engine with dual hypervisor backends: [Cloud Hypervisor](htt
 - **Multi-queue virtio-net** — TAP devices created with per-vCPU queue pairs; configurable ring depth (`--queue-size`, default 512); TSO/UFO/csum offload enabled by default
 - **TC redirect I/O path** — veth ↔ TAP wired via ingress qdisc + mirred redirect (no bridge in the data path)
 - **DNS configuration** — custom DNS servers injected into VMs via kernel cmdline (OCI) or cloud-init network-config (cloudimg)
-- **Cloud-init metadata** — automatic NoCloud cidata FAT12 disk for cloudimg VMs (hostname, root password, multi-NIC Netplan v2 network-config); cidata is automatically skipped on subsequent boots
+- **Cloud-init metadata** — automatic NoCloud cidata FAT12 disk for cloudimg VMs (hostname, configurable user/password via `--user`/`--password`, multi-NIC Netplan v2 network-config); cidata is automatically skipped on subsequent boots
 - **Hugepages** — automatic detection of host hugepage configuration; VM memory backed by hugepages when available
 - **Memory balloon** — 25% of memory returned via virtio-balloon (deflate-on-OOM, free-page reporting) when memory >= 256 MiB
 - **Graceful shutdown** — ACPI power-button for UEFI VMs with configurable timeout, fallback to SIGTERM → SIGKILL
@@ -48,7 +48,7 @@ Download pre-built binaries from [GitHub Releases](https://github.com/cocoonstac
 
 ```bash
 # Linux amd64
-curl -fsSL -o cocoon.tar.gz https://github.com/cocoonstack/cocoon/releases/download/v0.3.0/cocoon_0.3.0_Linux_x86_64.tar.gz
+curl -fsSL -o cocoon.tar.gz https://github.com/cocoonstack/cocoon/releases/download/v0.3.4/cocoon_0.3.4_Linux_x86_64.tar.gz
 tar -xzf cocoon.tar.gz
 install -m 0755 cocoon /usr/local/bin/
 
@@ -163,7 +163,6 @@ cocoon
 | `--log-level`     | `COCOON_LOG_LEVEL`             | `info`             | Log level: debug, info, warn, error    |
 | `--cni-conf-dir`  | `COCOON_CNI_CONF_DIR`          | `/etc/cni/net.d`   | CNI plugin config directory            |
 | `--cni-bin-dir`   | `COCOON_CNI_BIN_DIR`           | `/opt/cni/bin`     | CNI plugin binary directory            |
-| `--root-password` | `COCOON_DEFAULT_ROOT_PASSWORD` |                    | Default root password for cloudimg VMs |
 | `--dns`           | `COCOON_DNS`                   | `8.8.8.8,1.1.1.1`  | DNS servers for VMs (comma separated)  |
 
 ## VM Flags
@@ -182,6 +181,8 @@ Applies to `cocoon vm create`, `cocoon vm run`, and `cocoon vm debug`:
 | `--disk-queue-size` | `0` (default 512) | Virtio-blk ring depth per device (CH only, ignored by FC) |
 | `--network` | empty (default)  | CNI conflist name (empty = first conflist)     |
 | `--bridge`  | empty            | TAP-on-bridge mode (value is bridge device, e.g. `cni0`); mutually exclusive with `--network` |
+| `--user`    | `root`           | Guest username for cloud-init (cloudimg only)  |
+| `--password` | `cocoon`        | Guest password for cloud-init (cloudimg only)  |
 | `--no-direct-io` | `false`     | Disable O_DIRECT on writable disks (use page cache; CH only, useful for dev/test with few VMs) |
 | `--windows` | `false`          | Windows guest (UEFI boot, kvm_hyperv=on, no cidata) |
 
@@ -320,12 +321,14 @@ All `.conflist` files in `--cni-conf-dir` (default `/etc/cni/net.d`) are loaded
 Cloudimg VMs receive a NoCloud cidata disk (FAT12 with `CIDATA` volume label) containing:
 
 - **meta-data**: instance ID and hostname
-- **user-data**: `#cloud-config` with optional root password (`--root-password`)
+- **user-data**: `#cloud-config` with configurable user/password (`--user`/`--password`, defaults to `root`/`cocoon`)
 - **network-config**: Netplan v2 format with MAC-matched ethernets, static IP/gateway/DNS per NIC
 - **user-data write_files**: fallback `/etc/systemd/network/15-cocoon-id*.network` files matching current MAC (`MACAddress=`), used when netplan PERM-MAC matching cannot apply
 
 The cidata disk is **automatically excluded on subsequent boots** — after the first successful start, the VM record is marked as `first_booted` and the cidata disk is no longer attached, preventing cloud-init from re-running.
 
+Note: `--user`/`--password` only apply to **cloudimg** VMs (cloud-init). OCI VM images bake credentials at build time — cocoon OCI Dockerfiles annotate them via `LABEL cocoon.ssh.username` / `cocoon.ssh.password` for external tooling (e.g. glance, vk-cocoon).
+
 ## Windows Support
 
 Cocoon supports Windows guests via the `--windows` flag:

cmd/core/helpers.go

@@ -253,6 +253,8 @@ func VMConfigFromFlags(cmd *cobra.Command, image string) (*types.VMConfig, error
 	queueSize, _ := cmd.Flags().GetInt("queue-size")
 	diskQueueSize, _ := cmd.Flags().GetInt("disk-queue-size")
 	network, _ := cmd.Flags().GetString("network")
+	user, _ := cmd.Flags().GetString("user")
+	password, _ := cmd.Flags().GetString("password")
 	noDirectIO, _ := cmd.Flags().GetBool("no-direct-io")
 	windows, _ := cmd.Flags().GetBool("windows")
 
@@ -278,6 +280,8 @@ func VMConfigFromFlags(cmd *cobra.Command, image string) (*types.VMConfig, error
 		DiskQueueSize: diskQueueSize,
 		Image:         image,
 		Network:       network,
+		User:          user,
+		Password:      password,
 		NoDirectIO:    noDirectIO,
 		Windows:       windows,
 	}

cmd/root.go

@@ -40,7 +40,6 @@ var (
 		cmd.PersistentFlags().String("log-dir", "", "log directory")
 		cmd.PersistentFlags().String("cni-conf-dir", "", "CNI plugin config directory (default: /etc/cni/net.d)")
 		cmd.PersistentFlags().String("cni-bin-dir", "", "CNI plugin binary directory (default: /opt/cni/bin)")
-		cmd.PersistentFlags().String("root-password", "", "default root password for cloudimg VMs")
 		cmd.PersistentFlags().String("dns", "", `DNS servers for VMs, comma or semicolon separated (default: "8.8.8.8,1.1.1.1")`)
 		cmd.PersistentFlags().String("log-level", "", `log level: debug, info, warn, error (default: "info")`)
 
@@ -49,7 +48,6 @@ var (
 		_ = viper.BindPFlag("log_dir", cmd.PersistentFlags().Lookup("log-dir"))
 		_ = viper.BindPFlag("cni_conf_dir", cmd.PersistentFlags().Lookup("cni-conf-dir"))
 		_ = viper.BindPFlag("cni_bin_dir", cmd.PersistentFlags().Lookup("cni-bin-dir"))
-		_ = viper.BindPFlag("default_root_password", cmd.PersistentFlags().Lookup("root-password"))
 		_ = viper.BindPFlag("dns", cmd.PersistentFlags().Lookup("dns"))
 		_ = viper.BindPFlag("log.level", cmd.PersistentFlags().Lookup("log-level"))
 

cmd/vm/commands.go

@@ -159,6 +159,8 @@ func addVMFlags(cmd *cobra.Command) {
 	cmd.Flags().Int("disk-queue-size", 0, "virtio-blk ring depth per device (0 = default 512; CH only, ignored by FC)")                                                //nolint:mnd
 	cmd.Flags().String("network", "", "CNI conflist name (empty = default); mutually exclusive with --bridge")
 	cmd.Flags().String("bridge", "", "use TAP-on-bridge instead of CNI (value is bridge device, e.g. cni0); VM gets IP via DHCP from the bridge")
+	cmd.Flags().String("user", "root", "guest username for cloud-init (cloudimg only)")
+	cmd.Flags().String("password", "cocoon", "guest password for cloud-init (cloudimg only)")
 	cmd.Flags().Bool("no-direct-io", false, "disable O_DIRECT on writable disks (use page cache instead; CH only)")
 	cmd.Flags().Bool("windows", false, "Windows guest (UEFI boot, kvm_hyperv=on, no cidata)")
 }

config/config.go

@@ -51,9 +51,6 @@ type Config struct {
 	// CNIBinDir is the directory for CNI plugin binaries.
 	// Default: /opt/cni/bin.
 	CNIBinDir string `json:"cni_bin_dir" mapstructure:"cni_bin_dir"`
-	// DefaultRootPassword is the root password injected into cloudimg VMs
-	// via cloud-init metadata. Empty means no password is set.
-	DefaultRootPassword string `json:"default_root_password" mapstructure:"default_root_password"`
 	// DNS is a comma or semicolon separated list of DNS server addresses
 	// injected into VM network configuration.
 	// Env: COCOON_DNS. Default: "8.8.8.8,1.1.1.1".

hypervisor/cloudhypervisor/create.go

@@ -168,10 +168,11 @@ func (ch *CloudHypervisor) generateCidata(vmID string, vmCfg *types.VMConfig, ne
 		return fmt.Errorf("parse DNS servers: %w", err)
 	}
 	metaCfg := &metadata.Config{
-		InstanceID:   vmID,
-		Hostname:     vmCfg.Name,
-		RootPassword: ch.conf.DefaultRootPassword,
-		DNS:          dns,
+		InstanceID: vmID,
+		Hostname:   vmCfg.Name,
+		Username:   vmCfg.User,
+		Password:   vmCfg.Password,
+		DNS:        dns,
 	}
 	for _, n := range networkConfigs {
 		if n == nil || n.Mac == "" {

metadata/metadata.go

@@ -26,16 +26,23 @@ var (
 	// It also writes fallback systemd-networkd units matching current MAC so
 	// clone reinit can survive netplan PERM-MAC mismatch on later reboots.
 	userDataTmpl = template.Must(template.New("user-data").Funcs(tmplFuncs).Parse(`#cloud-config
-warnings:
-  dsid_missing_source: off
-{{- if .RootPassword}}
+{{- if .Password}}
 chpasswd:
   expire: false
   list:
-    - 'root:{{yamlQuote .RootPassword}}'
+    - '{{.Username}}:{{yamlQuote .Password}}'
 ssh_pwauth: true
+{{- if eq .Username "root"}}
 disable_root: false
 {{- end}}
+{{- if and .Username (ne .Username "root")}}
+runcmd:
+  - [sh, -c, 'id {{.Username}} >/dev/null 2>&1 || useradd -m -s /bin/bash -N {{.Username}}']
+  - [usermod, -aG, sudo, '{{.Username}}']
+  - [sh, -c, 'echo ''{{.Username}}:{{.Password}}'' | chpasswd']
+  - [sh, -c, 'echo ''{{.Username}} ALL=(ALL) NOPASSWD:ALL'' > /etc/sudoers.d/cocoon-{{.Username}}']
+{{- end}}
+{{- end}}
 {{- if .Networks}}
 write_files:
 {{- range $i, $n := .Networks}}
@@ -103,11 +110,12 @@ ethernets:
 
 // Config holds the inputs for generating cloud-init NoCloud metadata.
 type Config struct {
-	InstanceID   string
-	Hostname     string
-	RootPassword string
-	Networks     []NetworkInfo
-	DNS          []string // e.g. ["8.8.8.8", "8.8.4.4"]
+	InstanceID string
+	Hostname   string
+	Username   string
+	Password   string
+	Networks   []NetworkInfo
+	DNS        []string // e.g. ["8.8.8.8", "8.8.4.4"]
 }
 
 // NetworkInfo describes a single guest network interface for cloud-init.

metadata/metadata_test.go

@@ -8,7 +8,7 @@ import (
 
 func TestUserData_NoBootcmd(t *testing.T) {
 	cfg := &Config{
-		RootPassword: "test",
+		Username: "root", Password: "test",
 		Networks: []NetworkInfo{
 			{IP: "10.0.0.2", Prefix: 24, Mac: "aa:bb:cc:dd:ee:f0"},
 		},
@@ -26,9 +26,6 @@ func TestUserData_NoBootcmd(t *testing.T) {
 	if !strings.Contains(out, "root:test") {
 		t.Errorf("root password missing: %s", out)
 	}
-	if !strings.Contains(out, "dsid_missing_source: off") {
-		t.Errorf("cloud-init warning suppression missing: %s", out)
-	}
 	if !strings.Contains(out, "write_files:") {
 		t.Errorf("write_files missing: %s", out)
 	}
@@ -188,7 +185,7 @@ func TestGenerate_ProducesValidFAT12(t *testing.T) {
 	cfg := &Config{
 		InstanceID:   "test-id",
 		Hostname:     "test-vm",
-		RootPassword: "pass",
+		Username: "root", Password: "pass",
 		Networks: []NetworkInfo{
 			{IP: "10.0.0.2", Prefix: 24, Gateway: "10.0.0.1", Mac: "aa:bb:cc:dd:ee:ff"},
 		},
@@ -223,7 +220,7 @@ func TestGenerate_NoNetworks(t *testing.T) {
 	cfg := &Config{
 		InstanceID:   "test-id",
 		Hostname:     "test-vm",
-		RootPassword: "pass",
+		Username: "root", Password: "pass",
 	}
 
 	var buf bytes.Buffer
@@ -238,9 +235,6 @@ func TestGenerate_NoNetworks(t *testing.T) {
 	if strings.Contains(raw, "ethernets:") {
 		t.Error("network-config should not appear without networks")
 	}
-	if !strings.Contains(raw, "dsid_missing_source: off") {
-		t.Error("cloud-init warning suppression should always appear in user-data")
-	}
 	if strings.Contains(raw, "write_files:") {
 		t.Error("write_files should not appear without networks")
 	}

os-image/ubuntu/22.04/Dockerfile

@@ -1,5 +1,6 @@
 # Use the latest Ubuntu 22.04 (Jammy) LTS
 FROM ubuntu:22.04
+LABEL cocoon.ssh.username="root" cocoon.ssh.password="cocoon"
 
 ENV DEBIAN_FRONTEND=noninteractive