{
    "product": "Cenvero Stratum",
    "generated_at": "2026-11-16T13:19:22+00:00",
    "format": "cenvero-docs-v1",
    "document_count": 1,
    "documents": [
        {
            "slug": "compute/templates",
            "title": "Templates and Clones",
            "category": "Compute",
            "url": "https://stratum.cenvero.com/docs/compute/templates",
            "headings": [
                {
                    "level": 1,
                    "text": "Templates and Clones"
                },
                {
                    "level": 2,
                    "text": "Making a template"
                },
                {
                    "level": 2,
                    "text": "Who may use a template"
                },
                {
                    "level": 2,
                    "text": "Deleting a template"
                },
                {
                    "level": 2,
                    "text": "Cloning"
                },
                {
                    "level": 3,
                    "text": "A linked clone"
                },
                {
                    "level": 3,
                    "text": "A full clone"
                },
                {
                    "level": 3,
                    "text": "The guest's own identity"
                },
                {
                    "level": 2,
                    "text": "Over the API"
                },
                {
                    "level": 2,
                    "text": "See also"
                }
            ],
            "word_count": 1471,
            "markdown": "# Templates and Clones\n\nA **template** is a copy of a stopped machine's boot disk that new machines can\nstart from. A **clone** is a new machine made from a template, or from a stopped\nmachine. The operator makes templates and clones in the console, on the command\nline or over the API. Tenants cannot reach these routes.\n\n> Part of [Compute](/docs/compute/overview), in early access. Templates and clones\n> need a licence that includes Compute and is not frozen.\n\n## Making a template\n\nStop the machine, then make its boot disk into a template. In the console, open the\nmachine's **Summary** tab and, in its **Copies** card, choose **Make a template**. Give\nthe template a name, and tick **Let other tenants start machines from it** to share it.\nThe button is off while the machine runs, and says why.\n\nOn the command line:\n\n```bash\nsudo cenvero-str-ctl vm stop vm-3f9a1c2e\nsudo cenvero-str-ctl vm template vm-3f9a1c2e --name almalinux-9-web\n```\n\nThe answer names the template and the task that makes it. Follow\nthe task with `task log <task> --follow`. Over the API, `POST /api/v1/vms/{id}/templates`\ntakes `{\"name\", \"shared\"}`, and `shared` may be left out. The answer is **202**\nwith the template and its task.\n\nWhat the node does:\n\n- It copies the machine's boot disk into its image store, as a copy that depends on\n  nothing else. Later snapshots and backups of the machine cannot change the\n  template, and the template keeps working when the machine is deleted.\n- It checks the copy and records its SHA-256 and size.\n- It leaves the machine as it was: its disk, its data volumes and its settings do\n  not change.\n\nA machine whose boot disk is on a block pool makes a template the same way. The template is\na copy in the node's image store, whichever pool the machine is on.\n\nWhile the copy is made, the template is listed with the state `making`, and the\nmachine cannot start. Each template then reads `ready`, or `failed` when the copy\ncould not be finished. A copy that a restart of the node interrupts is marked\n`failed` too: delete it and make it again.\n\nTwo refusals are worth knowing:\n\n- A running machine cannot be made into a template: \"this machine is running; stop\n  it first\".\n- A suspended tenant's machines cannot be made into templates: \"this tenant is\n  suspended: its machines cannot start, be cloned or be made into templates\".\n\n## Who may use a template\n\nA template belongs to the tenant whose machine it was made from, or to the operator\nwhen the machine was the operator's own. Only that owner's machines can be made\nfrom it, unless it is **shared**.\n\n- **Sharing** is set at creation with `--shared`, or afterwards on the **Images**\n  page of the node, where a ready template has **Share with other tenants** (and\n  **Stop sharing** takes it back). Over the API, `PUT /api/v1/images/{id}` with\n  `{\"shared\": true}` (or `false` to stop sharing) answers **200** with the image. A\n  template is the only image with a sharing setting: a base image is usable by every\n  machine.\n- A shared template lets other tenants' machines start from it, and those machines\n  read the template's whole content: its data, its files and anything else on the\n  disk it was made from. Share a template only with that in mind.\n- **Stop sharing** is refused while another tenant's machine starts from the template.\n  The answer says how many: \"1 machine(s) of other tenants start from this template:\n  delete them before you stop sharing it, or give each a full clone and delete the\n  original\". To stop sharing, delete those machines first, or give each one a full\n  clone and delete the original. A full clone copies the whole disk, so the copy\n  depends on nothing else. Then stop sharing again. Machines that belong to the\n  operator are not counted, since the operator already holds the node's disks.\n- A machine that may not use a template is refused with \"this template belongs to\n  another tenant; ask an administrator to mark it shared\".\n- A change to sharing is recorded as an event, and in the audit log. If the change\n  cannot be recorded, nothing changes, and the answer says so: \"the sharing change\n  could not be recorded, so nothing changed: try again\".\n\n## Deleting a template\n\nA template can be deleted when no machine is made from it. While a machine uses it,\nthe delete is refused, and the answer names the machine. A template that is still\nbeing made cannot be deleted either: wait for it to finish, or for it to fail.\n\n## Cloning\n\nThere are two kinds of clone. Both give the new machine its own identity.\n\n### A linked clone\n\nA linked clone is a machine created from a template, as from any image. In the console,\nchoose the template as the image in the create wizard. On the command line:\n\n```bash\nsudo cenvero-str-ctl vm create --name web-02 --tenant t-acme --image img-8c2d6a10 \\\n  --vcpus 2 --memory 2048 --network net-acme-web\n```\n\nIts boot disk starts from the template and keeps only its own changes, so it starts\nat once and takes little space at first. The template cannot be deleted while a\nclone uses it.\n\nOn a block pool, a template is copied to the pool once, the first time a machine is made\nthere from it. Every later machine on that pool is a linked clone of that copy. The pools\nare described on [Storage pools](/docs/compute/storage-pools).\n\n### A full clone\n\nA full clone copies a stopped machine's boot disk into a new machine that stands on\nits own. The source must be stopped. In the console, its **Copies** card has **Clone**,\nwhich asks for the new machine's **Name** and its **Network**. On the command line:\n\n```bash\nsudo cenvero-str-ctl vm clone vm-3f9a1c2e --name web-02 --network net-acme-web \\\n  --hostname web-02 --tenant t-acme\n```\n\n`--network` is repeated for each network the clone needs. `--hostname` defaults to\nthe clone's name, and `--tenant` names the tenant the clone belongs to; it defaults\nto the source's tenant.\n\nOver the API, `POST /api/v1/vms/{id}/clone` takes `{\"name\", \"networks\", \"hostname\",\n\"tenant_id\"}`. Each entry in `networks` is `{\"network_id\"}`, with an `\"ip\"` when you\nwant one. The answer is **202** with the new machine and its task. A source that\nruns is refused with \"this machine cannot be cloned while it runs: stop it first\".\n\nA clone's boot disk can be kept on a block pool. The copy can go from a directory pool to a\nblock pool, from a block pool to a directory pool, or from one block pool to another. Over\nthe API, `pool` names the pool the clone's boot disk is kept on. On the command line,\n`vm clone --pool` does the same. The default pool is used when it is left out.\n[Storage pools](/docs/compute/storage-pools) describes the kinds of pool.\n\n- Only the boot disk is copied. The source's data volumes stay with the source.\n- The clone gets its own machine id, its own UUID and domain name, its own MAC\n  addresses on the networks you name, and its own cloud-init instance. Its first\n  boot is a first boot, so cloud-init configures it.\n- The clone is not protected, even when its source is.\n- Like any created machine, a clone starts when it is ready.\n- A clone counts against the tenant's machine limit, and a clone over the limit is\n  refused.\n\n### The guest's own identity\n\nA clone's guest identity, such as its SSH host keys and the machine id inside the\nguest, comes from the disk's contents. Cloud images regenerate those on their first\nboot, so most clones are safe to start. Windows needs its own preparation before a\nmachine is made into a template, and the node does not do that for you.\n\n## Over the API\n\n| Method | Path | Privilege | Answer |\n|---|---|---|---|\n| `POST` | `/api/v1/vms/{id}/templates` | `Image.Allocate` and `VM.Audit` on the machine | **202** with the template and its task; **409** while the machine runs |\n| `PUT` | `/api/v1/images/{id}` | `Image.Allocate` | **200** with the image; `{\"shared\": true or false}`. **409** while another tenant's machine starts from the template, when stopping sharing; **503** when the change cannot be recorded |\n| `POST` | `/api/v1/vms/{id}/clone` | `VM.Allocate` on the machine | **202** with the new machine and its task; **409** while the source runs |\n\nEvery route here needs a licence that includes Compute and is not frozen.\nReading the templates and the catalogue needs `Image.Audit`.\n\n## See also\n\n- [Images](/docs/compute/images), for base images and the image catalogue\n- [Snapshots, backups and schedules](/docs/compute/backups), for copies of a disk that restore to a volume\n- [Creating virtual machines](/docs/compute/virtual-machines)\n- [Current limits](/docs/compute/limits)\n"
        }
    ]
}