1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
|
(image-format)=
# Image format
Images contain a root file system and a metadata file that describes the image.
They can also contain templates for creating files inside an instance that uses the image.
Images can be packaged as either a unified image (single file) or a split image (two files).
## Content
Images for containers have the following directory structure:
```
metadata.yaml
rootfs/
templates/
```
Images for VMs have the following directory structure:
```
metadata.yaml
rootfs.img
templates/
```
For both instance types, the `templates/` directory is optional.
### Metadata
The `metadata.yaml` file contains information that is relevant to running the image in Incus.
It includes the following information:
```yaml
architecture: x86_64
creation_date: 1424284563
properties:
description: Debian 12 Intel 64bit
os: Debian
release: bookworm 12
templates:
...
```
The `architecture` and `creation_date` fields are mandatory.
The `properties` field contains a set of default properties for the image.
The `os`, `release`, `name` and `description` fields are commonly used, but are not mandatory.
The `templates` field is optional.
See {ref}`image_format_templates` for information on how to configure templates.
### Root file system
For containers, the `rootfs/` directory contains a full file system tree of the root directory (`/`) in the container.
Virtual machines use a `rootfs.img` `qcow2` file instead of a `rootfs/` directory.
This file becomes the main disk device.
(image_format_templates)=
### Templates (optional)
You can use templates to dynamically create files inside an instance.
To do so, configure template rules in the `metadata.yaml` file and place the template files in a `templates/` directory.
As a general rule, you should never template a file that is owned by a package or is otherwise expected to be overwritten by normal operation of an instance.
#### Template rules
For each file that should be generated, create a rule in the `metadata.yaml` file.
For example:
```yaml
templates:
/etc/hosts:
when:
- create
- rename
template: hosts.tpl
properties:
foo: bar
/etc/hostname:
when:
- start
template: hostname.tpl
/etc/network/interfaces:
when:
- create
template: interfaces.tpl
create_only: true
/home/foo/setup.sh:
when:
- create
template: setup.sh.tpl
create_only: true
uid: 1000
gid: 1000
mode: 755
```
The `when` key can be one or more of:
- `create` - run at the time a new instance is created from the image
- `copy` - run when an instance is created from an existing one
- `start` - run every time the instance is started
The `template` key points to the template file in the `templates/` directory.
You can pass user-defined template properties to the template file through the `properties` key.
Set the `create_only` key if you want Incus to create the file if it doesn't exist, but not overwrite an existing file.
The `uid`, `gid` and `mode` keys can be used to control the file ownership and permissions.
#### Template files
Template files use the [Pongo2](https://www.schlachter.tech/solutions/pongo2-template-engine/) format.
They always receive the following context:
| Variable | Type | Description |
|--------------|--------------------------------|-------------------------------------------------------------------------------------|
| `trigger` | `string` | Name of the event that triggered the template |
| `path` | `string` | Path of the file that uses the template |
| `instance` | `map[string]string` | Key/value map of instance properties (name, architecture, privileged and ephemeral) |
| `config` | `map[string]string` | Key/value map of the instance's configuration |
| `devices` | `map[string]map[string]string` | Key/value map of the devices assigned to the instance |
| `properties` | `map[string]string` | Key/value map of the template properties specified in `metadata.yaml` |
For convenience, the following functions are exported to the Pongo2 templates:
- `config_get("user.foo", "bar")` - Returns the value of `user.foo`, or `"bar"` if not set.
## Image tarballs
Incus supports two Incus-specific image formats: a unified tarball and split tarballs.
These tarballs can be compressed.
Incus supports a wide variety of compression algorithms for tarballs.
However, for compatibility purposes, you should use `gzip` or `xz`.
(image-format-unified)=
### Unified tarball
A unified tarball is a single tarball (usually `*.tar.xz`) that contains the full content of the image, including the metadata, the root file system and optionally the template files.
This is the format that Incus itself uses internally when publishing images.
It is usually easier to work with; therefore, you should use the unified format when creating Incus-specific images.
The image identifier for such images is the SHA-256 of the tarball.
(image-format-split)=
### Split tarballs
A split image consists of two files.
The first is a tarball containing the metadata and optionally the template files (usually `*.tar.xz`).
The second can be a tarball, `squashfs` or `qcow2` image containing the actual instance data.
For containers, the second file is most commonly a SquashFS-formatted file system tree, though it can also be a tarball of the same tree.
For virtual machines, the second file is always a `qcow2` formatted disk image.
Tarballs can be externally compressed (`.tar.xz`, `.tar.gz`, ...) whereas `squashfs` and `qcow2` can be internally compressed through their respective native compression options.
This format is designed to allow for easy image building from existing non-Incus rootfs tarballs that are already available.
You should also use this format if you want to create images that can be consumed by both Incus and other tools.
The image identifier for such images is the SHA-256 of the concatenation of the metadata and data files (in that order).
|
