How to prepare a Linux VM for conversion to an image

When to use

Before you convert a Linux VM into an image. Every machine from the image must get its own host name, users with passwords and SSH keys, network, and DNS.

In vStack Center, first-boot setup of a Linux machine is done by cloud-init. On every VM start, the cluster serves the machine its parameters over the second serial port (COM2) in the SmartOS data source format. Each VM gets its own instance identifier, so cloud-init on a copy treats the boot as the first one and sets the host name, users, and passwords again.

Hence the main difference from Windows: no separate generalization utility is needed. It is enough not to break cloud-init and to remove from the guest what must not end up in the copies.

Prerequisites

• The VM was created from a Linux catalog image with cloud-init — the image guest customization type is «Cloud-init: SmartOS». An image converted from a VM inherits from the VM profile the guest customization type, the OS type, the default user shell, and the network interface naming pattern.
• Everything that should go into the image is installed and configured inside the guest.
• You have root access to the VM — through the console or SSH.
• The VM meets the conversion requirements: only the boot disk, no clones, not a thin clone itself — see the prerequisites.

Steps

1. Check that cloud-init works. Do not remove or disable it, and do not change the data source settings. The state of the last boot:

   cloud-init status --long

   Expected: status: done with no errors.

2. Remove secrets from the guest. Delete saved passwords, tokens, users' private SSH keys, shell history, and working files that must not end up in the copies. Whatever stays on the disk is received by every machine from the image, and for an image shared across the cluster — by every VDC.

3. Clear the traces of this machine — following common practice for Linux images:

   cloud-init clean --logs
   truncate -s 0 /etc/machine-id

   The first command erases this machine's cloud-init state and logs. The second clears the systemd machine identifier: on the next boot the copy creates its own. By default, cloud-init recreates the SSH host keys on a new instance.

   If network settings in the guest are bound to a MAC address (udev rules, netplan or NetworkManager configurations with a MAC), remove that binding: a new VM gets a different MAC address.

4. Stop the VM from vStack Center: on the VM card, «Actions» → «Stop». Wait for the «Offline» status.

5. Convert the VM into an image following How to convert a VM to an image.

Verify the result

Create a new VM from the image with a new host name and root password and sign in through the console.

What to check	Expected
Sign-in	the password set at VM creation works
hostname	the host name set at VM creation
cloud-init status	status: done
Network	address and gateway from the VM network, DNS responds

Troubleshooting

Symptom	Cause	What to do
the host name and password are left from the source machine	cloud-init in the guest is disabled, removed, or set to another data source	the image is unusable: prepare a new source VM without touching cloud-init
the copy did not get an address	network settings in the guest are bound to the source VM's MAC address	prepare a new source VM with the MAC binding removed (step 3)
cloud-init status shows an error	one of the cloud-init modules failed	the cause is in /var/log/cloud-init.log

See also

• How to convert a VM to an image.
• How to prepare a Windows VM for conversion to an image.
• How to create, delete, and move a virtual machine — guest settings at VM creation.
• OS image library.

API methods

The API operations covered on this page are vms-stop, os-image-from-vm, and vms-create; see the API reference.