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

CMGS · CMGS · commit 69c01110708c · 2026-04-19T14:01:30.000+08:00
- 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.
diff --git a/KNOWN_ISSUES.md b/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`.
diff --git a/README.md b/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
@@ -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:
diff --git a/cmd/core/helpers.go b/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,
 	}
diff --git a/cmd/root.go b/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"))
 
diff --git a/cmd/vm/commands.go b/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)")
 }
diff --git a/config/config.go b/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".
diff --git a/hypervisor/cloudhypervisor/create.go b/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 == "" {
diff --git a/metadata/metadata.go b/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.
diff --git a/metadata/metadata_test.go b/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")
 	}
diff --git a/os-image/ubuntu/22.04/Dockerfile b/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
 
diff --git a/os-image/ubuntu/24.04-chrome/Dockerfile b/os-image/ubuntu/24.04-chrome/Dockerfile
@@ -1,4 +1,5 @@
 FROM ubuntu:24.04
+LABEL cocoon.ssh.username="root" cocoon.ssh.password="cocoon"
 
 ARG TARGETARCH
 ENV DEBIAN_FRONTEND=noninteractive
diff --git a/os-image/ubuntu/24.04-picoclaw/Dockerfile b/os-image/ubuntu/24.04-picoclaw/Dockerfile
@@ -1,4 +1,5 @@
 FROM ubuntu:24.04
+LABEL cocoon.ssh.username="root" cocoon.ssh.password="cocoon"
 
 ARG TARGETARCH
 ENV DEBIAN_FRONTEND=noninteractive
diff --git a/os-image/ubuntu/24.04-xface/Dockerfile b/os-image/ubuntu/24.04-xface/Dockerfile
@@ -1,4 +1,5 @@
 FROM ubuntu:24.04
+LABEL cocoon.ssh.username="root" cocoon.ssh.password="cocoon"
 
 ARG TARGETARCH
 ENV DEBIAN_FRONTEND=noninteractive
diff --git a/os-image/ubuntu/24.04/Dockerfile b/os-image/ubuntu/24.04/Dockerfile
@@ -1,5 +1,6 @@
 # Use the latest Ubuntu 24.04 (Noble) LTS
 FROM ubuntu:24.04
+LABEL cocoon.ssh.username="root" cocoon.ssh.password="cocoon"
 
 ENV DEBIAN_FRONTEND=noninteractive
 
diff --git a/types/vm.go b/types/vm.go
@@ -17,7 +17,13 @@ const (
 	VMStateError    VMState = "error"    // start or stop failed
 )
 
-var validName = regexp.MustCompile(`^[a-zA-Z0-9][a-zA-Z0-9._-]{0,62}$`)
+var (
+	validName     = regexp.MustCompile(`^[a-zA-Z0-9][a-zA-Z0-9._-]{0,62}$`)
+	validUsername = regexp.MustCompile(`^[a-z_][a-z0-9_-]{0,31}$`)
+	// shellUnsafe matches characters that could cause shell injection in
+	// cloud-init runcmd (backticks, $, semicolons, pipes, etc.).
+	shellUnsafe = regexp.MustCompile("[`$;|&(){}\\\\<>!]")
+)
 
 // VMConfig describes the resources requested for a new VM.
 type VMConfig struct {
@@ -28,9 +34,15 @@ type VMConfig struct {
 	QueueSize     int    `json:"queue_size,omitempty"`      // virtio-net ring depth per queue; 0 = default
 	DiskQueueSize int    `json:"disk_queue_size,omitempty"` // virtio-blk ring depth per device; 0 = default
 	Image         string `json:"image"`
-	Network       string `json:"network,omitempty"`      // CNI conflist name; empty = default
-	NoDirectIO    bool   `json:"no_direct_io,omitempty"` // disable O_DIRECT on writable disks
-	Windows       bool   `json:"windows,omitempty"`      // Windows guest: UEFI boot, kvm_hyperv=on, no cidata
+	Network       string `json:"network,omitempty"` // CNI conflist name; empty = default
+
+	NoDirectIO bool `json:"no_direct_io,omitempty"` // disable O_DIRECT on writable disks
+	Windows    bool `json:"windows,omitempty"`      // Windows guest: UEFI boot, kvm_hyperv=on, no cidata
+
+	// Transient cloud-init credentials — carried in-memory from CLI to cidata
+	// generation, never serialized to JSON or persisted in the VM record.
+	User     string `json:"-"`
+	Password string `json:"-"`
 }
 
 // Validate checks that VMConfig fields are within acceptable ranges.
@@ -56,6 +68,12 @@ func (cfg *VMConfig) Validate() error {
 	if cfg.DiskQueueSize < 0 {
 		return fmt.Errorf("--disk-queue-size must be non-negative, got %d", cfg.DiskQueueSize)
 	}
+	if cfg.User != "" && !validUsername.MatchString(cfg.User) {
+		return fmt.Errorf("--user %q is invalid: must be a lowercase Linux username (letters, digits, underscores, hyphens)", cfg.User)
+	}
+	if cfg.Password != "" && shellUnsafe.MatchString(cfg.Password) {
+		return fmt.Errorf("--password contains unsafe shell characters (backtick, $, ;, |, &, etc.)")
+	}
 	return nil
 }
 

Original file line number	Diff line number	Diff line change
`@@ -159,6 +159,8 @@ func addVMFlags(cmd *cobra.Command) {`
`159`	`159`	`cmd.Flags().Int("disk-queue-size", 0, "virtio-blk ring depth per device (0 = default 512; CH only, ignored by FC)") //nolint:mnd`
`160`	`160`	`cmd.Flags().String("network", "", "CNI conflist name (empty = default); mutually exclusive with --bridge")`
`161`	`161`	`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")`
	`162`	`+ cmd.Flags().String("user", "root", "guest username for cloud-init (cloudimg only)")`
	`163`	`+ cmd.Flags().String("password", "cocoon", "guest password for cloud-init (cloudimg only)")`
`162`	`164`	`cmd.Flags().Bool("no-direct-io", false, "disable O_DIRECT on writable disks (use page cache instead; CH only)")`
`163`	`165`	`cmd.Flags().Bool("windows", false, "Windows guest (UEFI boot, kvm_hyperv=on, no cidata)")`
`164`	`166`	`}`