Skip to content

docs: document per-frequency shell script MIME types #6891

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

Open
Ahmedaltu wants to merge 6 commits into
base: main
Choose a base branch
from
+23 −0
Open

docs: document per-frequency shell script MIME types #6891

Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
93a33dc
docs: document per-frequency shell script MIME types
Ahmedaltu May 25, 2026
1463c04
docs: clarify per-instance runs once per instance-id, not first boot …
Ahmedaltu May 26, 2026
73f17eb
docs: clarify per-once uses cloud-level semaphore state
Ahmedaltu May 26, 2026
fa78276
Merge branch 'docs/per-script-frequencies-v2' of https://github.com/A…
Ahmedaltu May 26, 2026
224afb4
docs: remove internal implementation details per review
Ahmedaltu May 27, 2026
76d86b2
docs: address review feedback on per-frequency MIME type descriptions
Ahmedaltu Jun 9, 2026
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
23 changes: 23 additions & 0 deletions doc/rtd/explanation/format/mime.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -77,4 +77,27 @@ Create user-data containing 3 shell scripts:

$ cloud-init devel make-mime -a always.sh:x-shellscript-per-boot -a instance.sh:x-shellscript-per-instance -a once.sh:x-shellscript-per-once

Per-frequency shell scripts
Comment thread
Ahmedaltu marked this conversation as resolved.
---------------------------

Cloud-init supports three MIME content types for controlling how often a
shell script runs, corresponding to the run frequencies described in
:ref:`module_frequency`:

Comment thread
Ahmedaltu marked this conversation as resolved.
``text/x-shellscript-per-boot``
The script runs on **every boot**. Useful for tasks that must be
repeated each time the instance starts, such as mounting ephemeral
storage or refreshing dynamic configuration.

``text/x-shellscript-per-instance``
The script runs **once per instance-id**. A new instance-id is
assigned each time a new instance is provisioned.

``text/x-shellscript-per-once``
The script runs **once**, tracked by a semaphore in
:file:`/var/lib/cloud/sem`. If cloud-init state is preserved — for
example, when an image is created from a running instance — the
semaphore persists and the script will not run again on instances
booted from that image.

Comment thread
Ahmedaltu marked this conversation as resolved.
.. _make-mime: https://github.com/canonical/cloud-init/blob/main/cloudinit/cmd/devel/make_mime.py
Loading