bootconfig: Preserve specific comments for kargs source tracking

Add support for preserving specific lines in BLS config files
that track kernel argument ownership by source. Comments matching the
prefix '# x-ostree-options-source-<name>' are parsed, stored, and
written back across parse/write roundtrips. This enables consumers
like rpm-ostree to record which kargs belong to which source (e.g.
TuneD) without adding non-standard key-value lines to BLS configs
that could confuse other tools.

Changes:
- OstreeBootconfigParser: add GPtrArray *comments field to preserve
  allowlisted magic comment lines through parse_at()/write_at() cycles
- Add public API: ostree_bootconfig_parser_{get,set}_comment()
  (Since: 2025.8) for reading and writing individual comment entries,
  exported in libostree-devel.sym under LIBOSTREE_2025.8. Private
  _get_comments_variant() for internal GVariant serialization.
- Staged deployment roundtrip: serialize magic comments as
  'bootconfig-comments' a{ss} in the staged GVariant and restore
  them via set_comment() during reload
- Update clone() and finalize() to handle the comments array
- Add 7 unit tests covering: empty state, get/set, variant
  serialization, BLS file parsing, write roundtrip, staging
  roundtrip, and empty-value (source disable) scenarios

Resolves: RHEL-135363
See: bootc-dev/bootc#899

Assisted-by: OpenCode (Claude Opus 4.6)
Signed-off-by: Joseph Marrero Corchado <jmarrero@redhat.com>

Author: jmarrero

Makefile-libostree.am

@@ -177,9 +177,9 @@ endif # USE_GPGME
 symbol_files = $(top_srcdir)/src/libostree/libostree-released.sym
 
 # Uncomment this include when adding new development symbols.
-#if BUILDOPT_IS_DEVEL_BUILD
-#symbol_files += $(top_srcdir)/src/libostree/libostree-devel.sym
-#endif
+if BUILDOPT_IS_DEVEL_BUILD
+symbol_files += $(top_srcdir)/src/libostree/libostree-devel.sym
+endif
 
 # http://blog.jgc.org/2007/06/escaping-comma-and-space-in-gnu-make.html
 wl_versionscript_arg = -Wl,--version-script=

apidoc/ostree-sections.txt

@@ -37,6 +37,8 @@ ostree_bootconfig_parser_write
 ostree_bootconfig_parser_write_at
 ostree_bootconfig_parser_set
 ostree_bootconfig_parser_get
+ostree_bootconfig_parser_set_comment
+ostree_bootconfig_parser_get_comment
 ostree_bootconfig_parser_set_overlay_initrds
 ostree_bootconfig_parser_get_overlay_initrds
 ostree_bootconfig_parser_get_tries_left

src/libostree/libostree-devel.sym

@@ -20,6 +20,12 @@
    - uncomment the include in Makefile-libostree.am
 */
 
+LIBOSTREE_2025.8 {
+global:
+  ostree_bootconfig_parser_get_comment;
+  ostree_bootconfig_parser_set_comment;
+} LIBOSTREE_2025.3;
+
 /* Stub section for the stable release *after* this development one; don't
  * edit this other than to update the year.  This is just a copy/paste
  * source.  Replace $LASTSTABLE with the last stable version, and $NEWVERSION

src/libostree/ostree-bootconfig-parser-private.h

@@ -8,4 +8,6 @@ G_BEGIN_DECLS
 
 const char *_ostree_bootconfig_parser_filename (OstreeBootconfigParser *self);
 
+GVariant *_ostree_bootconfig_parser_get_comments_variant (OstreeBootconfigParser *self);
+
 G_END_DECLS

src/libostree/ostree-bootconfig-parser.c

@@ -34,6 +34,13 @@ struct _OstreeBootconfigParser
 
   /* Additional initrds; the primary initrd is in options. */
   char **overlay_initrds;
+
+  /* Magic comments preserved across parse/write roundtrips.
+   * Each entry is the comment body (without the leading "# "),
+   * e.g. "x-ostree-options-source-tuned nohz=full isolcpus=1-3".
+   * Only comments matching allowed_comment_prefixes are preserved.
+   */
+  GPtrArray *comments;
 };
 
 typedef GObjectClass OstreeBootconfigParserClass;
@@ -57,6 +64,13 @@ ostree_bootconfig_parser_clone (OstreeBootconfigParser *self)
   parser->filename = g_strdup (self->filename);
   parser->overlay_initrds = g_strdupv (self->overlay_initrds);
 
+  if (self->comments)
+    {
+      parser->comments = g_ptr_array_new_with_free_func (g_free);
+      for (guint i = 0; i < self->comments->len; i++)
+        g_ptr_array_add (parser->comments, g_strdup (g_ptr_array_index (self->comments, i)));
+    }
+
   return parser;
 }
 
@@ -136,6 +150,25 @@ _ostree_bootconfig_parser_filename (OstreeBootconfigParser *self)
   return self->filename;
 }
 
+/* Allowlist of comment prefixes that should be preserved across parse/write
+ * roundtrips and the staged deployment serialization.  Only BLS comment lines
+ * (starting with '#') whose body (after stripping "# ") matches one of these
+ * prefixes are stored in self->comments.  To allow a new family of magic
+ * comments, add its prefix here.
+ */
+static const char *const allowed_comment_prefixes[] = { "x-ostree-options-source-", NULL };
+
+static gboolean
+is_allowed_comment (const char *comment_body)
+{
+  for (const char *const *p = allowed_comment_prefixes; *p != NULL; p++)
+    {
+      if (g_str_has_prefix (comment_body, *p))
+        return TRUE;
+    }
+  return FALSE;
+}
+
 /**
  * ostree_bootconfig_parser_parse_at:
  * @self: Parser
@@ -188,6 +221,21 @@ ostree_bootconfig_parser_parse_at (OstreeBootconfigParser *self, int dfd, const
               g_strfreev (items);
             }
         }
+      else if (*line == '#')
+        {
+          /* Check for magic comment lines that we preserve.
+           * Strip the leading '#' and any whitespace to get the body.
+           */
+          const char *body = line + 1;
+          while (*body == ' ' || *body == '\t')
+            body++;
+          if (is_allowed_comment (body))
+            {
+              if (!self->comments)
+                self->comments = g_ptr_array_new_with_free_func (g_free);
+              g_ptr_array_add (self->comments, g_strdup (body));
+            }
+        }
     }
 
   if (overlay_initrds)
@@ -324,6 +372,18 @@ ostree_bootconfig_parser_write_at (OstreeBootconfigParser *self, int dfd, const
       write_key (self, buf, k, v);
     }
 
+  /* Write preserved magic comments */
+  if (self->comments)
+    {
+      for (guint i = 0; i < self->comments->len; i++)
+        {
+          const char *comment = g_ptr_array_index (self->comments, i);
+          g_string_append (buf, "# ");
+          g_string_append (buf, comment);
+          g_string_append_c (buf, '\n');
+        }
+    }
+
   if (!glnx_file_replace_contents_at (dfd, path, (guint8 *)buf->str, buf->len,
                                       GLNX_FILE_REPLACE_NODATASYNC, cancellable, error))
     return FALSE;
@@ -339,6 +399,136 @@ ostree_bootconfig_parser_write (OstreeBootconfigParser *self, GFile *output,
                                             cancellable, error);
 }
 
+/**
+ * ostree_bootconfig_parser_get_comment:
+ * @self: Parser
+ * @comment_key: The comment key to look up (e.g. "x-ostree-options-source-tuned")
+ *
+ * Searches the stored magic comments for one whose first space-delimited
+ * token matches @comment_key.  Returns the value portion (everything after
+ * the first space), or NULL if not found.
+ *
+ * Returns: (nullable): The value string, or NULL if no matching comment exists.
+ *          The returned string is owned by the parser; do not free.
+ *
+ * Since: 2025.8
+ */
+const char *
+ostree_bootconfig_parser_get_comment (OstreeBootconfigParser *self, const char *comment_key)
+{
+  if (!self->comments)
+    return NULL;
+
+  const gsize key_len = strlen (comment_key);
+  for (guint i = 0; i < self->comments->len; i++)
+    {
+      const char *entry = g_ptr_array_index (self->comments, i);
+      if (g_str_has_prefix (entry, comment_key))
+        {
+          char after = entry[key_len];
+          if (after == '\0')
+            return ""; /* Key exists with no value */
+          if (after == ' ' || after == '\t')
+            return entry + key_len + 1; /* Skip the separator */
+        }
+    }
+  return NULL;
+}
+
+/**
+ * ostree_bootconfig_parser_set_comment:
+ * @self: Parser
+ * @comment_key: The comment key (e.g. "x-ostree-options-source-tuned")
+ * @value: (nullable): The value string (e.g. "nohz=full isolcpus=1-3"),
+ *         or NULL/empty to set a key-only comment
+ *
+ * Sets or replaces a magic comment entry.  If a comment with the same key
+ * already exists, it is replaced.  Otherwise a new entry is appended.
+ * The comment must match an allowed prefix (see allowed_comment_prefixes).
+ *
+ * Since: 2025.8
+ */
+void
+ostree_bootconfig_parser_set_comment (OstreeBootconfigParser *self, const char *comment_key,
+                                      const char *value)
+{
+  g_assert (is_allowed_comment (comment_key));
+
+  g_autofree char *new_entry = NULL;
+  if (value && *value)
+    new_entry = g_strdup_printf ("%s %s", comment_key, value);
+  else
+    new_entry = g_strdup (comment_key);
+
+  if (!self->comments)
+    self->comments = g_ptr_array_new_with_free_func (g_free);
+
+  /* Replace existing entry if present */
+  const gsize key_len = strlen (comment_key);
+  for (guint i = 0; i < self->comments->len; i++)
+    {
+      const char *entry = g_ptr_array_index (self->comments, i);
+      if (g_str_has_prefix (entry, comment_key))
+        {
+          char after = entry[key_len];
+          if (after == '\0' || after == ' ' || after == '\t')
+            {
+              g_free (self->comments->pdata[i]);
+              self->comments->pdata[i] = g_steal_pointer (&new_entry);
+              return;
+            }
+        }
+    }
+
+  /* Not found — append new entry */
+  g_ptr_array_add (self->comments, g_steal_pointer (&new_entry));
+}
+
+/**
+ * _ostree_bootconfig_parser_get_comments_variant:
+ * @self: Parser
+ *
+ * Returns a GVariant of type "a{ss}" containing magic comment entries
+ * whose prefix is in the allowed_comment_prefixes allowlist (currently
+ * "x-ostree-options-source-").  Each entry is a comment key mapped to
+ * its value string.  These are metadata set by consumers like rpm-ostree
+ * (e.g. "x-ostree-options-source-tuned" -> "nohz=full isolcpus=1-3")
+ * that need to survive the staged deployment serialization roundtrip.
+ *
+ * Returns: (nullable): A new floating #GVariant of type "a{ss}", or %NULL if
+ *          there are no matching comments.  The returned variant is floating;
+ *          if the caller is the definite owner, use g_variant_ref_sink().
+ */
+GVariant *
+_ostree_bootconfig_parser_get_comments_variant (OstreeBootconfigParser *self)
+{
+  if (!self->comments || self->comments->len == 0)
+    return NULL;
+
+  g_auto (GVariantBuilder) builder = OT_VARIANT_BUILDER_INITIALIZER;
+  g_variant_builder_init (&builder, (GVariantType *)"a{ss}");
+
+  for (guint i = 0; i < self->comments->len; i++)
+    {
+      const char *entry = g_ptr_array_index (self->comments, i);
+      /* Split into key and value on the first space/tab */
+      const char *sep = strpbrk (entry, " \t");
+      if (sep)
+        {
+          g_autofree char *key = g_strndup (entry, sep - entry);
+          const char *val = sep + 1;
+          g_variant_builder_add (&builder, "{ss}", key, val);
+        }
+      else
+        {
+          /* Key only, no value */
+          g_variant_builder_add (&builder, "{ss}", entry, "");
+        }
+    }
+
+  return g_variant_builder_end (&builder);
+}
+
 static void
 ostree_bootconfig_parser_finalize (GObject *object)
 {
@@ -347,6 +537,7 @@ ostree_bootconfig_parser_finalize (GObject *object)
   g_free (self->filename);
   g_strfreev (self->overlay_initrds);
   g_hash_table_unref (self->options);
+  g_clear_pointer (&self->comments, g_ptr_array_unref);
 
   G_OBJECT_CLASS (ostree_bootconfig_parser_parent_class)->finalize (object);
 }

src/libostree/ostree-bootconfig-parser.h

@@ -73,4 +73,12 @@ guint64 ostree_bootconfig_parser_get_tries_left (OstreeBootconfigParser *self);
 _OSTREE_PUBLIC
 guint64 ostree_bootconfig_parser_get_tries_done (OstreeBootconfigParser *self);
 
+_OSTREE_PUBLIC
+const char *ostree_bootconfig_parser_get_comment (OstreeBootconfigParser *self,
+                                                  const char *comment_key);
+
+_OSTREE_PUBLIC
+void ostree_bootconfig_parser_set_comment (OstreeBootconfigParser *self, const char *comment_key,
+                                           const char *value);
+
 G_END_DECLS

src/libostree/ostree-sysroot-deploy.c

@@ -3884,6 +3884,21 @@ ostree_sysroot_stage_tree_with_options (OstreeSysroot *self, const char *osname,
     g_variant_builder_add (builder, "{sv}", "overlay-initrds",
                            g_variant_new_strv ((const char *const *)opts->overlay_initrds, -1));
 
+  /* Serialize magic comments (e.g. "# x-ostree-options-source-tuned ...").
+   * These are metadata comments set by consumers that need to survive the
+   * staging roundtrip so they are preserved during finalization at shutdown.
+   * See allowed_comment_prefixes in ostree-bootconfig-parser.c.
+   */
+  {
+    OstreeBootconfigParser *bootconfig = ostree_deployment_get_bootconfig (deployment);
+    if (bootconfig)
+      {
+        GVariant *comments = _ostree_bootconfig_parser_get_comments_variant (bootconfig);
+        if (comments)
+          g_variant_builder_add (builder, "{sv}", "bootconfig-comments", comments);
+      }
+  }
+
   const char *parent = dirname (strdupa (_OSTREE_SYSROOT_RUNSTATE_STAGED));
   if (!glnx_shutil_mkdir_p_at (AT_FDCWD, parent, 0755, cancellable, error))
     return FALSE;

src/libostree/ostree-sysroot.c

@@ -28,6 +28,7 @@
 #include <sys/vfs.h>
 #include <sys/wait.h>
 
+#include "ostree-bootconfig-parser-private.h"
 #include "ostree-bootloader-aboot.h"
 #include "ostree-bootloader-grub2.h"
 #include "ostree-bootloader-syslinux.h"
@@ -1225,6 +1226,25 @@ _ostree_sysroot_reload_staged (OstreeSysroot *self, GError **error)
 
           _ostree_deployment_set_overlay_initrds (staged, overlay_initrds);
 
+          /* Restore magic comments (e.g. "# x-ostree-options-source-tuned ...")
+           * that were serialized during staging. These are metadata comments
+           * set by consumers like rpm-ostree that survive the staging roundtrip.
+           * See allowed_comment_prefixes in ostree-bootconfig-parser.c.
+           */
+          {
+            g_autoptr (GVariant) bootconfig_comments = NULL;
+            if (g_variant_dict_lookup (staged_deployment_dict, "bootconfig-comments", "@a{ss}",
+                                       &bootconfig_comments))
+              {
+                OstreeBootconfigParser *bootconfig = ostree_deployment_get_bootconfig (staged);
+                GVariantIter iter;
+                const char *key, *value;
+                g_variant_iter_init (&iter, bootconfig_comments);
+                while (g_variant_iter_next (&iter, "{&s&s}", &key, &value))
+                  ostree_bootconfig_parser_set_comment (bootconfig, key, value);
+              }
+          }
+
           self->staged_deployment = g_steal_pointer (&staged);
           self->staged_deployment_data = g_steal_pointer (&staged_deployment_data);
           /* We set this flag for ostree_deployment_is_staged() because that API