F43 Change Proposal: Release of Greenboot Rust Rewrite (self-contained)

Project Discussion Change Proposals
,
1

Release of Greenboot Rust Rewrite

This is a proposed Change for Fedora Linux.
This document represents a proposed Change. As part of the Changes process, proposals are publicly announced in order to receive community feedback. This proposal will only be implemented if approved by the Fedora Engineering Steering Committee.

Wiki
Announced

:link: Summary

A rewrite of Greenboot written in Rust will be released, designed for use with bootc and rpm-ostree based systems. This Greenboot release will have the same functionality as the original Bash release, which was only intended for rpm-ostree based systems.

:link: Owner

:link: Detailed Description

As this release is a Rust rewrite of the Bash Greenboot version, the functionality remains the same. It is detailed as follows:

Greenboot-RS exists to provide health check and rollback functionality to bootc and rpm-ostree based systems. It allows a user to specify health checks (scripts and binaries) to run every time the system boots. These health checks can be either required or wanted, with the difference of wanted checks not needing to succeed to allow a boot. If any required checks fail the system will reboot, and may rollback to a previous, working deployment if necessary.

Greenboot consists of two packages: greenboot and greenboot-default-health-checks. The former, greenboot comprises all the core functionalities of Greenboot. This includes checking provided scripts and binaries, rebooting when required scripts or binaries fail, and rolling back to a previous deployment if the problem remains unsolved. The second package, greenboot-default-health-checks, contains a series of optional health checks curated and provided by the Greenboot maintainers.

A Greenboot execution begins on boot with greenboot-healthcheck.service, which runs before systemd’s boot-complete.target. It launches /usr/libexec/greenboot/greenboot check, which runs the required.d and wanted.d scripts.

If any script in required.d fails, greenboot run the scripts in the red.d folder. Following this, a MOTD (Message of the Day) is created specifying which scripts have failed. Checks are then performed to determine if there’s a need for manual intervention. If not, then the system is rebooted.

If all scripts in required.d succeed:

  • boot-complete.target is reached.
  • The boot_counter GRUB env variable is unset and the boot_success GRUB env variable is set to 1.
  • Runs the scripts in the green.d folder. These are the scripts intended to be run after a successful update.
  • A MOTD with a success message is created.

:link: Feedback

Feedback from the community was positive regarding the Bash Greenboot release, and it is now included with every Fedora IoT installation. Various bugs and hiccups have been fixed as they have been found, and those changes are included within this Rust rewrite. This section will continue to be updated as more feedback is presented.

:link: Benefit to Fedora

This release is another step towards the adoption and support of bootc systems with Fedora. Originally, the Greenboot release was written in Bash and designed for use only with rpm-ostree based systems. This change releases a new version of Greenboot, Greenboot-RS, written in Rust and designed for usage with bootc and rpm-ostree based systems. This change will allow users to utilize the advantages of a bootc system, while still having the safety and reliability of Greenboot.

:link: Scope

  • Proposal owners:

    • Update with consolidation of services, such that all Greenboot services have been collapsed into a single service.
    • Update to allow seamless bootc upgrading. i.e. Upgrading from Greenboot to Greenboot-RS using only bootc upgrade.

  • Other developers: N/A

  • Release engineering: #Releng issue number N/A

  • Policies and guidelines: N/A (not needed for this Change)

  • Trademark approval: N/A (not needed for this Change)

  • Alignment with the Fedora Strategy: This change aligns with Fedora’s goal of increasing contributors, as it helps further the integration of bootc and Fedora IoT.

:link: Upgrade/compatibility impact

Current IoT users will experience a seamless transition to this new Greenboot release, using rpm-ostree upgrade to grab the new version. This new release will retain all the functionality of previous versions.

:link: Early Testing (Optional)

N/A

Do you require ‘QA Blueprint’ support? No

:link: How To Test

Once added to the Fedora IoT compose, you can test Greenboot-RS basic functionality by logging in via SSH. You should be greeted by this MOTD:

Boot Status is GREEN - Health Check SUCCESS

Ensure that the boot status and health check are both listed as above.

:link: User Experience

Current IoT Users should notice no changes, apart from their Greenboot version iterating after rpm-ostree upgrade. All functionality from previous Greenboot versions is retained, so the health check features they are used to will still remain.

Future IoT Users leveraging bootc will notice Greenboot support included when setting up IoT with bootc. These Users will now have access to the health check and rollback features Greenboot provides, and will start to see a Greenboot MOTD when booting their systems.

:link: Dependencies

N/A

:link: Contingency Plan

In the event of unexpected issues or setbacks with Greenboot-RS implementation, we will rollback to the previous Bash Greenboot implementation. As the release plan for Greenboot-RS involves creating a separate Greenboot-RS package, rollback will be accomplished by untagging the new Greenboot-RS package in Koji.

  • Contingency mechanism: Users may uninstall the Greenboot-RS package and the Bash Greenboot package will remain in service.
  • Contingency deadline: 08-12-2025
  • Blocks release? N/A (not a System Wide Change), Yes/No

:link: Documentation

N/A (not a System Wide Change)

:link: Release Notes

Last edited by @amoloney 2025-07-24T22:12:50Z

Last edited by @amoloney 2025-07-24T22:12:50Z

2

How do you feel about the proposal as written?

  • Strongly in favor
  • In favor, with reservations
  • Neutral
  • Opposed, but could be convinced
  • Strongly opposed
0 voters

If you are in favor but have reservations, or are opposed but something could change your mind, please explain in a reply.

We want everyone to be heard, but many posts repeating the same thing actually makes that harder. If you have something new to say, please say it. If, instead, you find someone has already covered what you’d like to express, please simply give that post a :heart: instead of reiterating. You can even do this by email, by replying with the heart emoji or just “+1”. This will make long topics easier to follow.

Please note that this is an advisory “straw poll” meant to gauge sentiment. It isn’t a vote or a scientific survey. See About the Change Proposals category for more about the Change Process and moderation policy.

3

I’m slightly confused by an apparent contradiction between the proposal text and the “contingency mechanism”: The proposal talks about the Rust rewrite replacing the bash-based greenboot.

But the “contingency mechanism” (which is what should be invoked distribution-wide in case the proposal fails, not what users can do!) seems to suggest that users are able to revert back to the non-Rust greenboot. But this won’t be possible if the packages are replaced.

(I also suggest that you talk to the Rust SIG wrt/ packaging the Rust rewrite.)

4

Can you add links in the change proposal to the old and new code bases?

1 Like
5

bash greenboot - GitHub - fedora-iot/greenboot: Generic Health Checking Framework for systemd
rust greenboor - GitHub - fedora-iot/greenboot-rs: Rust rewrite of greenboot

6

Great, can you edit the Wiki page and the main message here to add them there? Thanks

7

Thanks for the feedback!

To clarify, our plan is to release the Rust rewrite as a new package, greenboot-rs, which provides the same functionality as the current Bash-based greenboot. The Rust version will have a higher NVR and will use Provides, Obsoletes, and Conflicts to ensure that it replaces the Bash version cleanly and that both cannot be installed at the same time.

The contingency mechanism would be to untag greenboot-rs from the Fedora 43 compose if issues arise. In that case, the next compose will include the original Bash version as before. For users who have already pulled in the Rust version, rpm-ostree upgrade would result in a “downgrade” back to the Bash version automatically, since the Rust package would no longer be present in the repository.

We’ll update the proposal text to clarify this, and we’ll also ensure coordination with the Rust SIG as suggested.

1 Like
8

FWIW I don’t think untagging is a valid contingency mechanism. It’s a process that should be used only in emergencies (and usually only if the package hasn’t ever made it to published composes). In this case, reverting the Provides / Obsoletes / Conflicts changes should be done instead, IMO.

1 Like
9

This change proposal has now been submitted to FESCo with ticket #3459 for voting.

To find out more, please visit our Changes Policy documentation.

10

Thanks for the suggestion, we will adjust the proposal and do that instead.

2 Likes