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 5 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
5 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
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
---------------------------

Cloud-init supports three MIME content types for controlling how often a
shell script runs:

Comment on lines +80 to +85
Copy link
Copy Markdown
Author

@Ahmedaltu Ahmedaltu May 26, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Good point. The issue also requested rows in the content-type table and a multipart example. I can add those in a follow-up commit if the maintainers consider it in scope for this PR, or open a separate PR for those additions.

``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** (typically on first boot
for that instance). Useful for one-time instance setup tasks.

``text/x-shellscript-per-once``
The script runs **once per cloud-init state**, using the cloud-level
semaphore directory (:file:`/var/lib/cloud/sem`). A freshly
provisioned instance will normally run it once, but an instance
created from an image that preserves existing cloud-init state may
not. To allow it to run again, clean cloud-init state (for example,
remove :file:`/var/lib/cloud` or run :command:`cloud-init clean`).

.. _make-mime: https://github.com/canonical/cloud-init/blob/main/cloudinit/cmd/devel/make_mime.py
Loading