Create a VM
Updated
A classic VM is a normal Linux server: its own kernel, its own disk, cloud-init on first boot, and a terminal. If you have used a cloud instance before, none of this will surprise you.
Before you start you need an image to boot from. If you have not cached one yet, creating the machine fetches it. See First-run setup and Images and templates.
A storage pool is not a prerequisite. A host with a spare disk should have one, and the Storage page will say so, but a host whose only disk is its system disk keeps machine data there and is fully supported. See Storage pools for both cases.
Create one
Section titled “Create one”-
Open Instances and choose Create → Virtual machine.
Start from is Blank unless you pick a template, which fills the form in. See Images and templates.
-
Pick an image and size the machine.
Choose a distribution, then a release under it (or switch the picker to an image URL). Cached images start right away; a release the host does not hold yet is fetched as part of creating the machine. Leave Hostname empty and the host names the machine from its id.
Then pick a Size: Small (1 vCPU, 1 GB, 10 GiB, the default), Medium (2 vCPU, 4 GB, 20 GiB), Large (4 vCPU, 8 GB, 40 GiB), or Custom. The vCPU, memory and disk numbers underneath stay editable, and changing any of them turns the choice into Custom. A preset whose disk is smaller than the image is raised to the image’s size, and the form says so. The disk is a full copy of the image and can be larger than the original, so size it for what the workload will actually store. It cannot be smaller than the image: ask for less and the host gives you the image’s own size instead, and reserves that larger figure against the pool. The size you see committed is therefore the size the machine can grow into. Under Disk Size the form also states how much of the pool is free, and warns there when the size you asked for, with any new data volumes and the batch count, will not fit. A request the pool plainly cannot hold is refused with a 409 as it arrives, before any machine is created, and the reason is stated in GiB. That check is a floor and reserves no space, so a create it lets through can still fail at provisioning.
-
Attach it to a network.
This is the Network row under Hardware. Leaving the default is right for most hosts: the VM joins the host’s default VM network and gets an address from your existing DHCP server. To pin an address instead, switch the interface to a static IPv4 address and set the gateway and DNS servers yourself. You can remove every interface to create a machine with no network at all; it is then reached through its Shell or Rescue console, and its first boot cannot download anything.
-
Set up access.
Choose Sign in as root (the default) or a named user, and set a password, an SSH key under Access, or both. The form will not create a machine that nobody can sign in to. This is what cloud-init consumes the first time the machine boots.
-
Boot it.
Leave Boot after creation (under First boot) on and the machine starts as soon as it is built.
First-boot accounts
Section titled “First-boot accounts”The password field starts empty. The button beside it generates one, so two machines created from generated passwords never share a credential, and you can save it before creating the VM. Afterwards, the Cloud-Init panel only says whether a password is set; passwords are never returned by the UI or API. The form refuses to create a machine that has no password, no SSH key, no other account with a credential, and no cloud-config of your own.
A few behaviours are worth knowing before you change the defaults.
- A password does not open SSH. Setting a password for an account, root included, only lets it log in on the console. The two SSH policies are independent of passwords and keys. Password login over SSH offers Follow image (the default), Allow, and Deny (keys only). Root login over SSH offers Follow image, Allow, Key only, and Deny. Follow image writes nothing, so the image’s own sshd setting applies, and most cloud images refuse password logins. To log in over SSH with a password, or as root with one, choose Allow explicitly.
- Sign in as is root or A named user. Choosing a named user turns root
off for the machine and shows the user name and whether to grant
sudo. - An account with no password gets passwordless sudo. Granting sudo to an account that has no password to type would otherwise promise something the guest cannot deliver. An account with a password still has to enter it.
- Disabling root turns sudo on by default for the account you create in its place, since a machine with no root and no way to escalate is a machine you cannot administer.
- The login shell and the privilege tool come from the image. There is no
shell to choose: the host reads the image when it arrives (see
What the host reads from an image)
and gives your accounts the first shell the image has of ash, bash,
dash and zsh, in that order. Alpine accounts get
ashanddoas; Debian, Ubuntu, Fedora and the other mainstream images getbashandsudo. To use another shell, change it inside the VM withchsh. For a catalogue image that is not on the host yet, the cloud-config preview assumessudoand the image’s default shell; the VM itself is set up from the image’s facts once it is downloaded.
Some combinations are refused outright rather than producing a machine nobody
can reach: root disabled when no account has a password or an SSH key (unless
Console auto-login is on, or you supply your own cloud-config), an empty
password, and reusing a system account name such as daemon or www-data.
Resetting a distribution’s own default user, such as debian or ubuntu, is
allowed. Choosing Allow for root login over SSH while root is disabled is
accepted; it only takes effect once root is enabled inside the guest.
Reaching the machine
Section titled “Reaching the machine”The Instances list shows the VM moving to running, then reports the address it was observed at. SSH to that address with the credentials you configured.
If the state stays at Booting, the machine started but has not been seen on the network yet. After two minutes with no sign of this boot, the state becomes No boot signal: no DHCP lease, no answer from the VGA, no reply at a known address, and no traffic from the machine itself. That is not a failure and the host does not touch the machine, because a guest with a static address and no VGA looks exactly like this. Open its Rescue console (offered beside the other actions in this state) and look at the boot output. See Lifecycle and console.
Options worth knowing
Section titled “Options worth knowing”Below the essentials the form is a list of settings rows, each showing its current value while closed: Network and Storage under Hardware, Access and First boot under Access, and Processor, PCI devices, Cloud-config and Batch under Advanced. A row that contains an error opens by itself when you press Create.
| Option | Where it lives | Why you would use it |
|---|---|---|
| Additional interfaces | Hardware, Network | Attach a VM to more than one network, up to 15 interfaces. Interface 1 (eth0) is the primary; every other interface is a block of its own below it |
| MAC address, MTU, bandwidth cap | Hardware, Network | Pin an identity, match what a segment expects, or cap throughput. Every interface carries a cap, not only the primary. The MAC address is set on interface 1 and applies when you create one machine |
| Anti-spoof and port isolation | Hardware, Network | Restrict what the machine may send, and stop it talking to its neighbours |
| NIC offloads | Hardware, Network | On by default for much higher network throughput, except for images with known affected kernels. The form shows why it defaults to off. See NIC offloads |
| Data volumes | Hardware, Storage | Give the machine disks beyond its system disk, up to 25. These belong to the machine and are deleted with it |
| Disk I/O limits | Hardware, Storage | Cap IOPS and bandwidth so one machine cannot starve the others |
| vCPUs | Essentials, Size | Up to 254 per machine, subject to available host capacity |
| Max vCPUs and Max memory (online growth) | Advanced, Processor | Headroom for growing the machine while it runs. Both are fixed when the machine boots, so a machine created without them can only be resized by a reboot |
| CPU pinning, CPU topology | Advanced, Processor | Bind vCPUs to specific host CPUs for latency-sensitive workloads, or fix the socket, core and thread layout |
| Nested virtualization | Advanced, Processor | Off by default for new VMs. Turn it on to run virtualization workloads inside the guest. Requires nested virtualization to be enabled in the host kernel |
| PCI passthrough | Advanced, PCI devices | Hand a host device to the guest. See PCI passthrough |
| Cloud-config | Advanced, Cloud-config | Preview the generated document, and take it over with one of your own. See Images and templates |
| Boot after creation, Auto update | Access, First boot | Start the machine as soon as it is built; install package upgrades on first boot (without rebooting) |
| Console auto-login | Access, First boot | Anyone who can open the Rescue console gets a shell as the VM’s account without a password, useful when you are still setting up access. On by default. Available only for compatible images; otherwise the switch is disabled with the reason |
| Virtainer Guest Agent (VGA) | Access, First boot | Install Virtainer’s own guest agent: address reporting, consistent snapshots of a running machine, CPU and memory hot-plug, and the Shell. On by default. See The guest agent |
| Saved keys, key files, generated keys | Access | Fill in a public key already saved under Keys instead of pasting it again; Save a new key… adds one from a dialog over this form, without leaving it. From this computer… reads the public key from a .pub file (a private key is refused). Generate keypair makes a pair, adds the public half to the machine, and shows the private half once for you to save |
| Batch | Advanced, Batch | Create several identical machines in one go. See Images and templates |
Neither growth ceiling is set by default, and that is deliberate: the guest allocates memory for the processors it is allowed to grow to, so headroom you declare is memory the host cannot give to anyone else. Declare it on the machines you know you will resize, and leave it out of the rest. A machine created without them can have them added later on its Hardware tab while it is stopped.
The Virtainer Guest Agent (VGA) switch is on by default. The agent is Virtainer’s own, supplied by the host: nothing is downloaded, so it works on any distribution, with or without a network. A machine without it still works; the loss is limited to what has to ask the guest. Turn it off for a guest that must not run an agent as root: nothing about the agent then goes into the seed, and the instance’s Cloud-Init panel reads VGA setup: Off. A create request that leaves the field out gets the agent. See Virtainer Guest Agent (VGA).
To create more than one machine at once, set How many in the Batch row. The row is on the form whether or not you picked a template. See Images and templates.
Changing a VM later
Section titled “Changing a VM later”Most shape changes are made on the machine’s Hardware tab while it is created or stopped, and take effect at the next boot. A few apply to a running machine:
- vCPUs and memory can grow while it runs, up to the Max vCPUs and Max memory it was booted with. A machine booted without those ceilings has a fixed size while it runs; stop it, reserve headroom on the Hardware tab, and boot again.
- Memory reclaim can be changed while a Linux VM runs. It is currently disabled for Windows VMs.
- Network interfaces can be added, attached from the pool, and detached while it runs, and data volumes can be attached and detached too.
- Anti-spoof and port isolation take effect immediately, without a reboot.
Change Nested virtualization in the Hardware tab’s advanced options while the VM is stopped. Upgrading to Free 1.2 preserves existing VMs’ effective behaviour, including older exports and snapshots. An older VM may now correctly show On where the panel previously showed Off. AppVMs do not support this option.