Skip to content

Improve documentation for creating a custom XCP-ng template for Ubuntu #365

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 5 commits into from
Aug 1, 2025
Merged

Improve documentation for creating a custom XCP-ng template for Ubuntu #365

Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
c778289
doc: turn complex procedures into numbered lists
thomas-dkmt Jul 1, 2025
1e1d7f0
doc: complete instructions for making a custom ubuntu template
thomas-dkmt Jul 1, 2025
67be013
doc: correct indentation
thomas-dkmt Jul 1, 2025
25e411c
doc-ubuntu: move OVA procedure before ISO procedure
thomas-dkmt Jul 1, 2025
aed6434
doc: implement changes requested by samuel
thomas-dkmt Jul 21, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
214 changes: 151 additions & 63 deletions docs/guides/create-use-custom-xcpng-ubuntu-templates.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -34,116 +34,204 @@ Two approaches for creating a virtual machine will be presented in this post:

At the end of this step, the result will be essentially the same, and both solutions can be used for creating the template.

### From a cloud image in OVA format

Canonical (the Ubuntu company) provides Ubuntu images that have been configured to run on cloud systems. The [website](https://cloud-images.ubuntu.com) provides all versions of Ubuntu. XCP-NG supports the open virtual machine format OVA used by VMWare and VirtualBox systems.

1. Download an OVA file of [Ubuntu 22.04 version](https://cloud-images.ubuntu.com/jammy).

2. From the [Xen Orchestra](https://xen-orchestra.com) side menu, click on the **Import** option and choose the **VM** sub-option.

3. Drag and drop or select the file *jammy-server-cloudimg-amd64.ova* and if necessary, modify the parameters for creating the virtual machine by naming it *custom-cloud-ubuntu22.04*.

4. Click on **Import** and wait for the import to finish.

The creation of the virtual image from a cloud image in OVA format is complete. A template can now be created.

### From an ISO file

* Download an ISO file of Ubuntu 22.04.04 LTS version: [https://ubuntu.com/download/server](https://ubuntu.com/download/server)
1. Download an ISO file of Ubuntu 22.04 LTS version: [https://ubuntu.com/download/server](https://ubuntu.com/download/server)

In order to access the ISO file during the virtual machine creation step, it needs to be placed in an ISO storage repository. There are several types available (Local, NFS, or SMB). For this post, the first type will be used. Feel free to browse through this [post](https://xcp-ng.org/blog/2022/05/05/how-to-create-a-local-iso-repository-in-xcp-ng/) to learn how to create a local ISO storage repository. In the following, I assume that there is a local ISO storage repository on the XCP-NG host.
In order to access the ISO file during the virtual machine creation step, it needs to be placed in an ISO storage repository. There are several types available (Local, NFS, or SMB). For this post, the first type will be used. Feel free to browse through this [post](https://xcp-ng.org/blog/2022/05/05/how-to-create-a-local-iso-repository-in-xcp-ng/) to learn how to create a local ISO storage repository. In the following, I assume that there is a local ISO storage repository on the XCP-NG host.

* From the [Xen Orchestra](https://xen-orchestra.com) side menu, click on the **Import** option and choose the **Disk** sub-option.
2. From the [Xen Orchestra](https://xen-orchestra.com) side menu, click on the **Import** option and choose the **Disk** sub-option.

* Select the ISO repository from the SR dropdown where the ISO file will be uploaded.
3. Select the ISO repository from the SR dropdown where the ISO file will be uploaded.

* Drag and drop or select the file *ubuntu-22.04.4-live-server-amd64.iso*, click on **Import**, and wait for the import to finish.
4. Drag and drop or select the file *ubuntu-22.04.4-live-server-amd64.iso*, click on **Import**, and wait for the import to finish.

> You can also directly upload the ISO file to the server where the local ISO storage repository is located using the **scp** tool.
> You can also directly upload the ISO file to the server where the local ISO storage repository is located using the **scp** tool.

* From the [Xen Orchestra](https://xen-orchestra.com) side menu, click on the **New** option and choose the **VM** sub-option to create a new virtual machine.
5. From the [Xen Orchestra](https://xen-orchestra.com) side menu, click on the **New** option and choose the **VM** sub-option to create a new virtual machine.

* Select the Ubuntu Jammy Jellyfish 22.04 template (which is more of a loading profile than a template) and enter the following values for the parameters: custom-ubuntu22.04 for the name, 1 CPU, 4 GB of RAM, 10 GB of disk space, and choose the ISO file ubuntu-22.04.4-live-server-amd64.iso from the previously created local storage.
6. Select the Ubuntu Jammy Jellyfish 22.04 template (which is more of a loading profile than a template) and enter the following values for the parameters: custom-ubuntu22.04 for the name, 1 CPU, 4 GB of RAM, 10 GB of disk space, and choose the ISO file ubuntu-22.04.4-live-server-amd64.iso from the previously created local storage.

* During the Ubuntu installation steps, please ensure 1) to create only one partition to allow resizing later and 2) to install the OpenSSH server.
7. During the Ubuntu installation steps, please ensure:
1. to create only one partition to allow resizing later
2. to install the OpenSSH server:

![One single partition on the local disk](../../assets/img/screenshots/templatexcpng-ubuntu-partition.png)
![One single partition on the local disk](../../assets/img/screenshots/templatexcpng-ubuntu-partition.png)

* Once the installation is complete, restart the system while removing the drive containing the ISO file.
8. Once the installation is complete, restart the system while removing the drive containing the ISO file.

* Connect via the console provided by [Xen Orchestra](https://xen-orchestra.com) or via SSH and update the repositories and the system.
9. Connect via the console provided by [Xen Orchestra](https://xen-orchestra.com) or via SSH and update the repositories and the system:

```
$ sudo apt update
$ sudo apt dist-upgrade
```
```
$ sudo apt update
$ sudo apt dist-upgrade
```

* Install the package *xe-guest-utilities-latest* to improve communication between the XCP-NG hypervisor and the virtual machine ([Guest tools](https://docs.xcp-ng.org/vms/#%EF%B8%8F-guest-tools)).
10. Install the package *xe-guest-utilities-latest* to improve communication between the XCP-NG hypervisor and the virtual machine ([Guest tools](https://docs.xcp-ng.org/vms/#%EF%B8%8F-guest-tools)):

```
$ sudo apt install xe-guest-utilities
```
```
$ sudo apt install xe-guest-utilities
```

* Update the *cloud-init* package.
11. Update the *cloud-init* package:

```
$ sudo apt install cloud-init
```
```
$ sudo apt install cloud-init
```

* Install the package *cloud-initramfs-growroot* to automatically resize the root partition of the disk upon virtual machine startup.
12. Install the package *cloud-initramfs-growroot* to automatically resize the root partition of the disk upon virtual machine startup:

```
$ sudo apt install cloud-initramfs-growroot
```
```
$ sudo apt install cloud-initramfs-growroot
```

* Configure the [Cloud-init](https://cloud-init.io/) data sources by selecting *NoCloud*, *ConfigDrive*, and *OpenStack*.
13. Configure the [Cloud-init](https://cloud-init.io/) data sources by selecting *NoCloud*, *ConfigDrive*, and *OpenStack*:

```
$ sudo dpkg-reconfigure cloud-init
```
```
$ sudo dpkg-reconfigure cloud-init
```

* Delete the file */etc/cloud/cloud.cfg.d/99-installer.cfg* to reset certain default [Cloud-init](https://cloud-init.io/) configurations when starting a virtual machine.
14. Prevent Cloud-init from removing */etc/cloud/ds-identify.cfg*.

```
$ sudo rm -f /etc/cloud/cloud.cfg.d/99-installer.cfg
```
Since we're going to override the default */etc/cloud/ds-identify.cfg*, we need to prevent *cloud-init clean* from deleting it, which it does by default.

* Delete the file */etc/cloud/cloud.cfg.d/subiquity-disable-cloudinit-networking.cfg* to allow modification of network settings.
To do this, run the following command:

```
$ sudo rm -f /etc/cloud/cloud.cfg.d/subiquity-disable-cloudinit-networking.cfg
```
```
chmod a-x /etc/cloud/clean.d/99-installer
```

* Delete the directory */var/lib/cloud/instance* which contains default settings related to the ongoing installation.
:::info

```
$ sudo rm -rf /var/lib/cloud/instance
```
*/etc/cloud/clean.d/99-installer* is part of the cloud-init package and will reappear on cloud-init package update. It should not be removed, which is why we recommend to apply a *chmod a-x* on it.

* Delete the file */etc/netplan/00-installer-config.yaml* which is the current network configuration so that the new configuration can be applied after reboot.
:::

```
$ sudo rm -f /etc/netplan/00-installer-config.yaml
```
15. To reset certain default [Cloud-init](https://cloud-init.io/) configurations when starting a virtual machine:

* Before shutting down the virtual machine, you can install any additional repositories you want. Once this step is completed, you can shut down the virtual machine.
**If using an Ubuntu version older than 24.04**

```
$ sudo shutdown now
```
Delete the file */etc/cloud/cloud.cfg.d/99-installer.cfg*:

The creation of the virtual image *custom-ubuntu22.04* from an ISO file is complete, and a template can now be created.
```
sudo rm -f /etc/cloud/cloud.cfg.d/99-installer.cfg
```

**Note:** for Ubuntu 24.04, you will need to delete the */etc/cloud/cloud-init.disabled* file, which disables Cloud-Init by default, and the */etc/netplan/50-cloud-init.yaml* file for network configuration.
**If using Ubuntu 24.04 or a later version**

Delete the file */etc/cloud/cloud.cfg.d/90-installer-network.cfg*:

```
sudo rm -f /etc/cloud/cloud.cfg.d/90-installer-network.cfg
```

### From a cloud image in OVA format
16. **If using an Ubuntu version older than 24.04**, delete the file */etc/cloud/cloud.cfg.d/subiquity-disable-cloudinit-networking.cfg* to allow modification of network settings:

Canonical (the Ubuntu company) provides Ubuntu images that have been configured to run on cloud systems. The [website](https://cloud-images.ubuntu.com) provides all versions of Ubuntu. XCP-NG supports the open virtual machine format OVA used by VMWare and VirtualBox systems.
```
$ sudo rm -f /etc/cloud/cloud.cfg.d/subiquity-disable-cloudinit-networking.cfg
```

* Download an OVA file of [Ubuntu 22.04 version](https://cloud-images.ubuntu.com/jammy).
17. Clean runtime cloud-init leftovers and logs:

* From the [Xen Orchestra](https://xen-orchestra.com) side menu, click on the **Import** option and choose the **VM** sub-option.
```
$ cloud-init clean --logs --seed
```

* Drag and drop or select the file *jammy-server-cloudimg-amd64.ova* and if necessary, modify the parameters for creating the virtual machine by naming it *custom-cloud-ubuntu22.04*.
18. Delete the file */etc/netplan/00-installer-config.yaml* which is the current network configuration so that the new configuration can be applied after reboot:

* Click on **Import** and wait for the import to finish.
```
$ sudo rm -f /etc/netplan/00-installer-config.yaml
```

The creation of the virtual image from a cloud image in OVA format is complete. A template can now be created.
19. To ensure the template correctly generates a new machine ID, applies the static IP address when deploying a VM, and clears existing cloud-init logs to facilitate troubleshooting in case something goes wrong, run the following commands:

```
sudo rm -rf /var/lib/cloud/instances /var/lib/cloud/instance
sudo rm -rf /var/log/cloud-init.log /var/log/cloud-init*
sudo rm -f /etc/netplan/50-cloud-init.yaml
sudo rm -f /etc/cloud/cloud.cfg.d/90-installer-network.cfg
sudo truncate -s 0 /etc/machine-id
```

20. Clean up the APT cache. It's useful for two reasons:
- Saving some storage space
- Prevent future problems in installing packages, due to the cache growing stale

To clean up the APT cache, run the following command:

```
apt-get clean
```

21. Remove SSH host keys, so they can be regenerated when first booting a of newly provisioned VM.

To do this, run this command:

```
find /etc/ssh/ -type f -name 'ssh_host_*' -delete
```

:::warning

Not removing the SSH host keys will cause all your VMs to have same the host keys, which could be considered a security issue.

:::

22. Before shutting down the virtual machine, you can install any additional repositories you want. Once this step is completed, you can shut down the virtual machine:

```
$ sudo shutdown now
```

The creation of the virtual image *custom-ubuntu22.04* from an ISO file is complete, and a template can now be created.

:::tip

* For Ubuntu 24.04, you will need to delete the */etc/cloud/cloud-init.disabled* file, which disables Cloud-Init by default, and the */etc/netplan/50-cloud-init.yaml* file for network configuration.
* For your network configuration YAML:
* Use the following format:

```yaml
#cloud-config
network:
version: 2
ethernets:
eth0:
dhcp4: false
addresses:
- 10.0.2.6/27
gateway4: 10.0.2.1
nameservers:
addresses:
- 10.0.2.1
- 1.1.1.1
```
* Make sure your IP address uses the [Classless Inter-Domain Routing (CIDR)](https://en.wikipedia.org/wiki/Classless_Inter-Domain_Routing#CIDR_notation) notation.\
CIDR notation specifies an IP address, a slash ('/') character, and a decimal number (for instance: `198.51.100.14/24`).
* If a problem occurs when creating or using your template, go to `/var/log` and look for `cloud-init.log` to troubleshoot the issue.
:::

## Template creation

The template creation step involves converting an existing virtual machine into the format used for templates. This step is irreversible in the sense that the virtual machine will no longer appear in the list of virtual machines in [Xen Orchestra](https://xen-orchestra.com).

* Select one of the two virtual machines created earlier (in this section, it's the virtual machine created from the ISO that was chosen) and click on the **Advanced** tab.
1. Select one of the two virtual machines created earlier (in this section, it's the virtual machine created from the ISO that was chosen) and click on the **Advanced** tab.

* Click on **Convert to template** and confirm the creation.
2. Click on **Convert to template** and confirm the creation.

The template has been created and added to the list of existing templates. The created template is named after the virtual machine *custom-ubuntu22.04*.

Expand Down