diff --git a/doc/rtd/explanation/boot.rst b/doc/rtd/explanation/boot.rst index 7fe3a6e9bb49..ac1f61931253 100644 --- a/doc/rtd/explanation/boot.rst +++ b/doc/rtd/explanation/boot.rst @@ -187,95 +187,7 @@ finished, the :command:`cloud-init status --wait` subcommand can help block external scripts until ``cloud-init`` is done without having to write your own ``systemd`` units dependency chains. See :ref:`cli_status` for more info. -.. _boot-First_boot_determination: - -First boot determination -======================== - -``Cloud-init`` has to determine whether or not the current boot is the first -boot of a new instance, so that it applies the appropriate configuration. On -an instance's first boot, it should run all "per-instance" configuration, -whereas on a subsequent boot it should run only "per-boot" configuration. This -section describes how ``cloud-init`` performs this determination, as well as -why it is necessary. - -When it runs, ``cloud-init`` stores a cache of its internal state for use -across stages and boots. - -If this cache is present, then ``cloud-init`` has run on this system -before [#not-present]_. There are two cases where this could occur. Most -commonly, the instance has been rebooted, and this is a second/subsequent -boot. Alternatively, the filesystem has been attached to a *new* instance, -and this is the instance's first boot. The most obvious case where this -happens is when an instance is launched from an image captured from a -launched instance. - -By default, ``cloud-init`` attempts to determine which case it is running -in by checking the instance ID in the cache against the instance ID it -determines at runtime. If they do not match, then this is an instance's -first boot; otherwise, it's a subsequent boot. Internally, ``cloud-init`` -refers to this behaviour as ``check``. - -This behaviour is required for images captured from launched instances to -behave correctly, and so is the default that generic cloud images ship with. -However, there are cases where it can cause problems [#problems]_. For these -cases, ``cloud-init`` has support for modifying its behaviour to trust the -instance ID that is present in the system unconditionally. This means that -``cloud-init`` will never detect a new instance when the cache is present, -and it follows that the only way to cause ``cloud-init`` to detect a new -instance (and therefore its first boot) is to manually remove -``cloud-init``'s cache. Internally, this behaviour is referred to as -``trust``. - -To configure which of these behaviours to use, ``cloud-init`` exposes the -``manual_cache_clean`` configuration option. When ``false`` (the default), -``cloud-init`` will ``check`` and clean the cache if the instance IDs do -not match (this is the default, as discussed above). When ``true``, -``cloud-init`` will ``trust`` the existing cache (and therefore not clean it). - -Manual cache cleaning -===================== - -``Cloud-init`` ships a command for manually cleaning the cache: -:command:`cloud-init clean`. See :ref:`cli_clean`'s documentation for further -details. - -Reverting ``manual_cache_clean`` setting ----------------------------------------- - -Currently there is no support for switching an instance that is launched with -``manual_cache_clean: true`` from ``trust`` behaviour to ``check`` behaviour, -other than manually cleaning the cache. - -.. warning:: If you want to capture an instance that is currently in ``trust`` - mode as an image for launching other instances, you **must** manually clean - the cache. If you do not do so, then instances launched from the captured - image will all detect their first boot as a subsequent boot of the captured - instance, and will not apply any per-instance configuration. - - This is a functional issue, but also a potential security one: - ``cloud-init`` is responsible for rotating SSH host keys on first boot, - and this will not happen on these instances. - -.. [#not-present] It follows that if this cache is not present, - ``cloud-init`` has not run on this system before, so this is - unambiguously this instance's first boot. - -.. [#problems] A couple of ways in which this strict reliance on the presence - of a datasource has been observed to cause problems: - - - If a cloud's metadata service is flaky and ``cloud-init`` cannot - obtain the instance ID locally on that platform, ``cloud-init``'s - instance ID determination will sometimes fail to determine the current - instance ID, which makes it impossible to determine if this is an - instance's first or subsequent boot (`#1885527`_). - - If ``cloud-init`` is used to provision a physical appliance or device - and an attacker can present a datasource to the device with a different - instance ID, then ``cloud-init``'s default behaviour will detect this as - an instance's first boot and reset the device using the attacker's - configuration (this has been observed with the - :ref:`NoCloud datasource` in `#1879530`_). +See the :ref:`first boot documentation ` to learn how +cloud-init decides that a boot is the "first boot". .. _generator: https://www.freedesktop.org/software/systemd/man/systemd.generator.html -.. _#1885527: https://bugs.launchpad.net/ubuntu/+source/cloud-init/+bug/1885527 -.. _#1879530: https://bugs.launchpad.net/ubuntu/+source/cloud-init/+bug/1879530 diff --git a/doc/rtd/explanation/first_boot.rst b/doc/rtd/explanation/first_boot.rst new file mode 100644 index 000000000000..2348e6e2c0a8 --- /dev/null +++ b/doc/rtd/explanation/first_boot.rst @@ -0,0 +1,91 @@ +.. _First_boot_determination: + +First boot determination +======================== + +``Cloud-init`` has to determine whether or not the current boot is the first +boot of a new instance, so that it applies the appropriate configuration. On +an instance's first boot, it should run all "per-instance" configuration, +whereas on a subsequent boot it should run only "per-boot" configuration. This +section describes how ``cloud-init`` performs this determination, as well as +why it is necessary. + +When it runs, ``cloud-init`` stores a cache of its internal state for use +across stages and boots. + +If this cache is present, then ``cloud-init`` has run on this system +before [#not-present]_. There are two cases where this could occur. Most +commonly, the instance has been rebooted, and this is a second/subsequent +boot. Alternatively, the filesystem has been attached to a *new* instance, +and this is the instance's first boot. The most obvious case where this +happens is when an instance is launched from an image captured from a +launched instance. + +By default, ``cloud-init`` attempts to determine which case it is running +in by checking the instance ID in the cache against the instance ID it +determines at runtime. If they do not match, then this is an instance's +first boot; otherwise, it's a subsequent boot. Internally, ``cloud-init`` +refers to this behaviour as ``check``. + +This behaviour is required for images captured from launched instances to +behave correctly, and so is the default that generic cloud images ship with. +However, there are cases where it can cause problems [#problems]_. For these +cases, ``cloud-init`` has support for modifying its behaviour to trust the +instance ID that is present in the system unconditionally. This means that +``cloud-init`` will never detect a new instance when the cache is present, +and it follows that the only way to cause ``cloud-init`` to detect a new +instance (and therefore its first boot) is to manually remove +``cloud-init``'s cache. Internally, this behaviour is referred to as +``trust``. + +To configure which of these behaviours to use, ``cloud-init`` exposes the +``manual_cache_clean`` configuration option. When ``false`` (the default), +``cloud-init`` will ``check`` and clean the cache if the instance IDs do +not match (this is the default, as discussed above). When ``true``, +``cloud-init`` will ``trust`` the existing cache (and therefore not clean it). + +Manual cache cleaning +===================== + +``Cloud-init`` ships a command for manually cleaning the cache: +:command:`cloud-init clean`. See :ref:`cli_clean`'s documentation for further +details. + +Reverting ``manual_cache_clean`` setting +---------------------------------------- + +Currently there is no support for switching an instance that is launched with +``manual_cache_clean: true`` from ``trust`` behaviour to ``check`` behaviour, +other than manually cleaning the cache. + +.. warning:: If you want to capture an instance that is currently in ``trust`` + mode as an image for launching other instances, you **must** manually clean + the cache. If you do not do so, then instances launched from the captured + image will all detect their first boot as a subsequent boot of the captured + instance, and will not apply any per-instance configuration. + + This is a functional issue, but also a potential security one: + ``cloud-init`` is responsible for rotating SSH host keys on first boot, + and this will not happen on these instances. + +.. [#not-present] It follows that if this cache is not present, + ``cloud-init`` has not run on this system before, so this is + unambiguously this instance's first boot. + +.. [#problems] A couple of ways in which this strict reliance on the presence + of a datasource has been observed to cause problems: + + - If a cloud's metadata service is flaky and ``cloud-init`` cannot + obtain the instance ID locally on that platform, ``cloud-init``'s + instance ID determination will sometimes fail to determine the current + instance ID, which makes it impossible to determine if this is an + instance's first or subsequent boot (`#1885527`_). + - If ``cloud-init`` is used to provision a physical appliance or device + and an attacker can present a datasource to the device with a different + instance ID, then ``cloud-init``'s default behaviour will detect this as + an instance's first boot and reset the device using the attacker's + configuration (this has been observed with the + :ref:`NoCloud datasource` in `#1879530`_). + +.. _#1885527: https://bugs.launchpad.net/ubuntu/+source/cloud-init/+bug/1885527 +.. _#1879530: https://bugs.launchpad.net/ubuntu/+source/cloud-init/+bug/1879530 diff --git a/doc/rtd/explanation/index.rst b/doc/rtd/explanation/index.rst index 503c7098a000..8a1adc4639ed 100644 --- a/doc/rtd/explanation/index.rst +++ b/doc/rtd/explanation/index.rst @@ -11,9 +11,10 @@ knowledge and become better at using and configuring ``cloud-init``. :maxdepth: 1 introduction.rst + format.rst configuration.rst boot.rst - format.rst + first_boot.rst events.rst instancedata.rst vendordata.rst