State Script

The Mender Client has the ability to run pre- and postinstall scripts, before and after it writes the root file system. However, Mender state scripts are more general and useful than pre/postinstall scripts because they run between any state transition, not just (before/after) the install state.

Common use cases are:

• Enable/disable network connectivity before and after checking for an update to reduce bandwidth.
• Migrate persistent data during a software update.
• User or application confirmation before a reboot. This is common in applications which have a UI, or that provide critical functionality (e.g network routers).
• Run additional sanity checks before committing to the update.

States

A State script can be run before (Enter) or after (Leave) each of the following states.

• Idle: The Mender client idles and waits for the next action to handle. At this stage, no communication with the server, or downloads are in progress.
• Sync: At this stage the Mender client will either send or update its inventory to the server, or check if an update is available. This requires communication with the server.
• Download: When an update is ready at the server side Mender downloads it (streams it) to the inactive rootfs partition.
• ArtifactInstall: Swap the active and inactive partitions through interaction with the bootloader.
• ArtifactReboot: Reboots the device. Note: the Enter scripts run prior to reboot; the Leave scripts run after.
• ArtifactCommit: If the new image in the passive partition passes all the integrity checks, the Mender client will mark the update as successful and continue running from this partition. The commit makes the update persistent. A pre-script here can add custom integrity checks beyond what the Mender client provides out of the box.
• ArtifactRollback: If the new update fails any of the above mentioned integrity checks, the Mender client will revert the update payload. At this point, scripts in this state can help revert migrations done as a part of the update.
• ArtifactRollbackReboot: Some update types - most notably rootfs images - require a reboot, if any of the integrity checks fail. This state runs right before the client reboots back (i.e., rollback) into the old image partition.
• ArtifactFailure: if any of the States with an "Artifact" prefix fail, execute this state. Note: this state always runs after the ArtifactRollback and the ArtifactRollbackReboot states.

Most of the states also have an Error transition which runs if some error occurs while executing any script for the given state.

Execution

State scripts run as pre- and post-scripts to every state in the Mender state machine shown above. The state in which a given script runs is determined by the script name and index.

Exit codes from a state script can control the execution of the Mender state machine. Depending on the return code from the script the Mender client will:

• Move on to the next state, if successful.
• Retry this state at a later time.
• Mark the update as failed, and report the error to the server.

Logging

The Mender client collects logs during an update. In case of a failure, these logs are sent to the Mender server. The output from state scripts are included in these logs. This is useful when troubleshooting intermittent update failures.

Further reading

To learn more, have a look at the tutorial on how to implement State scripts.