5
Curtin exposes a number of configuration options for controlling Curtin
6
behavior during installation.
11
Curtin's top level config keys are as follows:
14
- apt_mirrors (``apt_mirrors``)
15
- apt_proxy (``apt_proxy``)
16
- block-meta (``block``)
17
- debconf_selections (``debconf_selections``)
18
- disable_overlayroot (``disable_overlayroot``)
20
- http_proxy (``http_proxy``)
21
- install (``install``)
24
- multipath (``multipath``)
25
- network (``network``)
26
- power_state (``power_state``)
27
- reporting (``reporting``)
28
- restore_dist_interfaces: (``restore_dist_interfaces``)
29
- sources (``sources``)
31
- storage (``storage``)
33
- system_upgrade (``system_upgrade``)
34
- write_files (``write_files``)
39
Configure APT mirrors for ``ubuntu_archive`` and ``ubuntu_security``
41
**ubuntu_archive**: *<http://local.archive/ubuntu>*
43
**ubuntu_security**: *<http://local.archive/ubuntu>*
45
If the target OS includes /etc/apt/sources.list, Curtin will replace
46
the default values for each key set with the supplied mirror URL.
51
ubuntu_archive: http://local.archive/ubuntu
52
ubuntu_security: http://local.archive/ubuntu
57
Curtin will configure an APT HTTP proxy in the target OS
59
**apt_proxy**: *<URL to APT proxy>*
63
apt_proxy: http://squid.mirror:3267/
68
Configure how Curtin selects and configures disks on the target
69
system without providing a custom configuration (mode=simple).
71
**devices**: *<List of block devices for use>*
73
The ``devices`` parameter is a list of block device paths that Curtin may
74
select from with choosing where to install the OS.
76
**boot-partition**: *<dictionary of configuration>*
78
The ``boot-partition`` parameter controls how to configure the boot partition
79
with the following parameters:
81
**enabled**: *<boolean>*
83
Enabled will forcibly setup a partition on the target device for booting.
85
**format**: *<['uefi', 'gpt', 'prep', 'mbr']>*
87
Specify the partition format. Some formats, like ``uefi`` and ``prep``
88
are restricted by platform characteristics.
90
**fstype**: *<filesystem type: one of ['ext3', 'ext4'], defaults to 'ext4'>*
92
Specify the filesystem format on the boot partition.
94
**label**: *<filesystem label: defaults to 'boot'>*
96
Specify the filesystem label on the boot partition.
108
label: my-boot-partition
113
Curtin will update the target with debconf set-selection values. Users will
114
need to be familiar with the package debconf options. Users can probe a
115
packages' debconf settings by using ``debconf-get-selections``.
117
**selection_name**: *<debconf-set-selections input>*
119
``debconf-set-selections`` is in the form::
121
<packagename> <packagename/option-name> <type> <value>
127
cloud-init cloud-init/datasources multiselect MAAS
128
lxd lxd/bridge-name string lxdbr0
129
set2: lxd lxd/setup-bridge boolean true
135
Curtin disables overlayroot in the target by default.
137
**disable_overlayroot**: *<boolean: default True>*
141
disable_overlayroot: False
146
Curtin configures grub as the target machine's boot loader. Users
147
can control a few options to tailor how the system will boot after
150
**install_devices**: *<list of block device names to install grub>*
152
Specify a list of devices onto which grub will attempt to install.
154
**replace_linux_default**: *<boolean: default True>*
156
Controls whether grub-install will update the Linux Default target
157
value during installation.
159
**update_nvram**: *<boolean: default False>*
161
Certain platforms, like ``uefi`` and ``prep`` systems utilize
162
NVRAM to hold boot configuration settings which control the order in
163
which devices are booted. Curtin by default will not attempt to
164
update the NVRAM settings to preserve the system configuration.
165
Users may want to force NVRAM to be updated such that the next boot
166
of the system will boot from the installed device.
173
replace_linux_default: False
179
Curtin will export ``http_proxy`` value into the installer environment.
181
**http_proxy**: *<HTTP Proxy URL>*
185
http_proxy: http://squid.proxy:3728/
191
Configure Curtin's install options.
193
**log_file**: *<path to write Curtin's install.log data>*
195
Curtin logs install progress by default to /var/log/curtin/install.log
197
**post_files**: *<List of files to read from host to include in reporting data>*
199
Curtin by default will post the ``log_file`` value to any configured reporter.
201
**save_install_config**: *<Path to save merged curtin configuration file>*
203
Curtin will save the merged configuration data into the target OS at
204
the path of ``save_install_config``. This defaults to /root/curtin-install-cfg.yaml
209
log_file: /tmp/install.log
213
save_install_config: /root/myconf.yaml
218
Configure how Curtin selects which kernel to install into the target image.
219
If ``kernel`` is not configured, Curtin will use the default mapping below
220
and determine which ``package`` value by looking up the current release
221
and current kernel version running.
224
**fallback-package**: *<kernel package-name to be used as fallback>*
226
Specify a kernel package name to be used if the default package is not
229
**mapping**: *<Dictionary mapping Ubuntu release to HWE kernel names>*
231
Default mapping for Releases to package names is as follows::
250
**package**: *<Linux kernel package name>*
252
Specify the exact package to install in the target OS.
257
fallback-package: linux-image-generic
258
package: linux-image-generic-lts-xenial
261
- 4.4.0: -my-custom-kernel
266
Curtin can use kexec to "reboot" into the target OS.
270
Enable rebooting with kexec.
279
Curtin will detect and autoconfigure multipath by default to enable
280
boot for systems with multipath. Curtin does not apply any advanced
281
configuration or tuning, rather it uses distro defaults and provides
282
enough configuration to enable booting.
284
**mode**: *<['auto', ['disabled']>*
286
Defaults to auto which will configure enough to enable booting on multipath
287
devices. Disabled will prevent curtin from installing or configuring
290
**overwrite_bindings**: *<boolean>*
292
If ``overwrite_bindings`` is True then Curtin will generate new bindings
293
file for multipath, overriding any existing binding in the target image.
299
overwrite_bindings: True
304
Configure networking (see Networking section for details).
306
**network_option_1**: *<option value>*
315
mac_address: "c0:d6:9f:2c:e8:80"
322
Curtin can configure the target machine into a specific power state after
323
completing an installation. Default is to do nothing.
325
**delay**: *<Integer seconds to delay change in state>*
327
Curtin will wait ``delay`` seconds before changing the power state.
329
**mode**: *<New power state is one of: [halt, poweroff, reboot]>*
331
Curtin will transition the node into one of the new states listed.
333
``halt`` will stop a machine, but may not cut the power to the system.
334
``poweroff`` will stop a machine and request it shut off the power.
335
``reboot`` will perform a platform reset.
337
**message**: *<message string>*
339
The ``message`` string will be broadcast to system consoles prior to
353
Configure installation reporting (see Reporting section for details).
361
endpoint: http://localhost:8000/
364
restore_dist_interfaces
365
~~~~~~~~~~~~~~~~~~~~~~~
366
Curtin can restore a copy of /etc/network/interfaces built in to cloud images.
368
**restore_dist_interfaces**: *<boolean>*
370
If True, then Curtin will restore the interfaces file into the target.
375
restore_dist_interfaces: True
380
Specify the root image to install on to the target system. The URI also
381
configures the method used to copy the image to the target system.
383
**sources**: *<List of source URIs>*
385
``source URI`` may be one of:
387
- **dd-**: Use ``dd`` command to write image to target.
388
- **cp://**: Use ``rsync`` command to copy source directory to target.
389
- **file://**: Use ``tar`` command to extract source to target.
390
- **http[s]://**: Use ``wget | tar`` commands to extract source to target.
392
**Example Cloud-image**::
395
- https://cloud-images.ubuntu.com/xenial/current/xenial-server-cloudimg-amd64-root.tar.gz
397
**Example Custom DD image**::
400
- dd-img: https://localhost/raw_images/centos-6-3.img
402
**Example Copy from booted environment**::
408
**Example Copy from local tarball**::
411
- file:///tmp/root.tar.gz
416
Curtin installation executes in stages. At each stage, Curtin will look for
417
a list of commands to run at each stage by reading in from the Curtin config
418
*<stage_name>_commands* which is a dictionary and each key contains a list
419
of commands to run. Users may override the stages value to control
420
what curtin stages execute. During each stage, the commands are executed
421
in C Locale sort order. Users should name keys in a NN-XXX format where NN
422
is a two-digit number to exercise control over execution order.
424
The following stages are defined in Curtin and
427
- **early**: *Preparing for Installation*
429
This stage runs before any actions are taken for installation. By default
430
this stage does nothing.
432
- **partitioning**: *Select and partition disks for installation*
434
This stage runs ``curtin block-meta simple`` by default.
436
- **network**: *Probe and configure networking*
438
This stage runs ``curtin net-meta auto`` by default.
440
- **extract**: *Writing install sources to disk*
442
This stage runs ``curtin extract`` by default.
444
- **extract**: *Writing install sources to disk*
446
This stage runs ``curtin extract`` by default.
448
- **curthooks**: *Configuring installed system*
450
This stage runs ``curtin curthooks`` by default.
452
- **hooks**: *Finalizing installation*
454
This stage runs ``curtin hook`` by default.
456
- **late**: *Executing late commands*
458
This stage runs after Curtin has completed the installation. By default
459
this stage does nothing.
461
**Example Custom Stages**::
463
# Skip the whole install and just run `mystage`
464
stages: ['early', 'late', 'mystage']
466
00-cmd: ['/usr/bin/foo']
468
**Example Early and Late commands**::
471
99-cmd: ['echo', 'I ran last']
472
00-cmd: ['echo', 'I ran first']
474
50-cmd: ['curtin', 'in-target' '--', 'touch', '/etc/disable_overlayroot']
479
Curtin can configure a swapfile on the filesystem in the target system.
480
Size settings can be integer or string values with suffix. Curtin
481
supports the following suffixes which multiply the value.
484
- **K[B]**: *1 << 10*
485
- **M[B]**: *1 << 20*
486
- **G[B]**: *1 << 30*
487
- **T[B]**: *1 << 40*
489
Curtin will use a heuristic to configure the swapfile size if the ``size``
490
parameter is not set to a specific value. The ``maxsize`` sets the upper
491
bound of the heuristic calculation.
493
**filename**: *<path to swap file>*
495
Configure the filename of the swap file. Defaults to /swap.img
497
**maxsize**: *<Size string>*
499
Configure the max size of the swapfile, defaults to 8GB
501
**size**: *<Size string>*
503
Configure the exact size of the swapfile. Setting ``size`` to 0 will
516
Control if Curtin runs `dist-upgrade` in target after install. Defaults to
519
**enabled**: *<boolean>*
529
Curtin supports writing out arbitrary data to a file.
530
``write_files`` accepts a dictionary of entries formatted as follows:
532
**path**: *<path and filename to save content>*
534
Specify the name and location of where to write the content.
536
**permissions**: *<Unix permission string>*
538
Specify the permissions mode as an integer or string of numbers.
540
**content**: *<data>*
550
f0VMRgIBAQAAAAAAAAAAAAIAPgABAAAAwARAAAAAAABAAAAAAAAAAJAVAAAAAAA
551
f2: {path: /file2, content: "foobar", permissions: '0666'}
added
removed
doc/topics/config.rst
