From aa8e8e5d53dab508a7dc12c5281e80dec7c4e771 Mon Sep 17 00:00:00 2001 From: Alberto Contreras Date: Thu, 25 Jul 2024 10:22:02 +0200 Subject: [PATCH] doc: Update docs on boothooks Improve explanation on #cloud-boothook for end-users. SC-1657 Fixes GH-4542 Co-authored-by: Calvin Mwadime --- doc/examples/boothook.txt | 3 ++ doc/rtd/explanation/format.rst | 51 ++++++++++++++++++++++++++++------ doc/rtd/reference/examples.rst | 7 +++++ 3 files changed, 52 insertions(+), 9 deletions(-) create mode 100644 doc/examples/boothook.txt diff --git a/doc/examples/boothook.txt b/doc/examples/boothook.txt new file mode 100644 index 00000000000..1c1d52d4589 --- /dev/null +++ b/doc/examples/boothook.txt @@ -0,0 +1,3 @@ +#cloud-boothook +#!/bin/sh +echo 192.168.1.130 us.archive.ubuntu.com > /etc/hosts diff --git a/doc/rtd/explanation/format.rst b/doc/rtd/explanation/format.rst index c1eda9006d9..216eb91d0b7 100644 --- a/doc/rtd/explanation/format.rst +++ b/doc/rtd/explanation/format.rst @@ -157,17 +157,50 @@ a MIME archive. ``cloud-boothook`` ================== -This content is `boothook` data. It is stored in a file under -:file:`/var/lib/cloud` and executed immediately. This is the earliest `hook` -available. Note, that there is no mechanism provided for running only once. The -`boothook` must take care of this itself. +One line ``#cloud-boothook`` header and then executable payload. -It is provided with the instance id in the environment variable -``INSTANCE_ID``. This could be made use of to provide a 'once-per-instance' -type of functionality. +This is run very early on the boot process, during the +:ref:`Network boot stage`, even before ``cc_bootcmd``. -Begins with: ``#cloud-boothook`` or ``Content-Type: text/cloud-boothook`` when -using a MIME archive. +This can be used when something has to be configured very early on boot, +potentially on every boot, with less convenience as ``cc_bootcmd`` but more +flexibility. + +.. note:: + Boothooks are execute on every boot. + The environment variable ``INSTANCE_ID`` will be set to the current instance + ID. ``INSTANCE_ID`` can be used to implement a `once-per-instance` type of + functionality. + +Begins with: ``#cloud-boothook``. + +Example with simple script +-------------------------- + +.. code-block:: bash + + #cloud-boothook + #!/bin/sh + echo 192.168.1.130 us.archive.ubuntu.com > /etc/hosts + +Example of once-per-instance script +----------------------------------- + +.. code-block:: bash + + #cloud-boothook + #!/bin/sh + + PERSIST_ID=/var/lib/cloud/first-instance-id + _id="" + if [ -r $PERSIST_ID ]; then + _id=$(cat /var/lib/cloud/first-instance-id) + fi + + if [ -z $_id ] || [ $INSTANCE_ID != $_id ]; then + echo 192.168.1.130 us.archive.ubuntu.com >> /etc/hosts + fi + sudo echo $INSTANCE_ID > $PERSIST_ID Part-handler ============ diff --git a/doc/rtd/reference/examples.rst b/doc/rtd/reference/examples.rst index c9829e49cd2..fe2703031ac 100644 --- a/doc/rtd/reference/examples.rst +++ b/doc/rtd/reference/examples.rst @@ -77,6 +77,13 @@ Run commands on first boot :language: yaml :linenos: +Run commands on very early at every boot +======================================== + +.. literalinclude:: ../../examples/boothook.txt + :language: bash + :linenos: + Install arbitrary packages ==========================