Add inline config field to plugin.yaml

Add the 'config' field to plugin.yaml entries, allowing plugin
configuration to be embedded directly using a YAML block scalar (|).
The literal text is written to a temporary file at startup and passed
to the plugin as an argument. Only scalar values are accepted;
structured YAML is rejected to preserve quoting semantics that
plugins like txn_box rely on.

Made-with: Cursor

Author: Damian Meden

doc/admin-guide/files/plugin.yaml.en.rst

@@ -71,6 +71,30 @@ configuration entry remains in the file for easy re-enabling.
 with ``$`` designate |TS| configuration variables and will be expanded
 to their current value before the plugin is loaded.
 
+``config``
+----------
+
+**Optional.** Inline configuration content specified as a YAML scalar.
+The text is written to a temporary file at startup and the path is
+passed to the plugin as an argument, so existing plugins work without
+modification.
+
+.. tip::
+
+   Use a literal block scalar (``|``) to preserve exact text including
+   newlines and quoting -- this is important for plugins like
+   ``txn_box.so`` that assign special meaning to YAML quoting.
+
+.. note::
+
+   Structured YAML (mappings or sequences) is rejected because
+   re-serializing through a YAML emitter strips quoting semantics that
+   some plugins depend on.  For example, ``txn_box.so`` distinguishes
+   ``"literal"`` (a quoted string) from ``extractor-name`` (an unquoted
+   reference), and that distinction would be lost after a round-trip
+   through ``YAML::Emitter``.  Supporting structured YAML may be
+   revisited in the future.
+
 ``load_order``
 --------------
 
@@ -139,6 +163,8 @@ legacy :file:`plugin.config` format:
    plugin without removing or commenting out the line.
 *  **Explicit load ordering** — use ``load_order`` to control loading
    priority independent of file position.
+*  **Inline configuration** — embed a plugin's config content directly
+   via the ``config`` field instead of maintaining a separate file.
 *  **Variable expansion** — ``$record`` references in ``params`` are
    expanded to their current value at load time (same as
    :file:`plugin.config`).
@@ -207,6 +233,70 @@ Despite the YAML sequence order, the actual load order is:
    Use gaps between ``load_order`` values (e.g. 100, 200, 300) so new
    plugins can be inserted later without renumbering.
 
+Inline Configuration
+--------------------
+
+The ``config`` field lets you embed a plugin's configuration directly in
+:file:`plugin.yaml` instead of maintaining a separate file. At startup, |TS|
+writes the content to a temporary file in the configuration directory and passes
+the path of that file to the plugin as an argument — exactly the same way a
+``params`` entry pointing to an external file would work. The plugin reads the
+file as usual; it has no knowledge the content was inlined.
+
+Use the YAML literal block scalar (``|``) to provide the content:
+
+.. code-block:: yaml
+
+   plugins:
+     - path: header_rewrite.so
+       config: |
+         cond %{SEND_RESPONSE_HDR_HOOK}
+            set-header X-Debug "true"
+
+The text after ``|`` is preserved exactly (including newlines and
+indentation). It is written to a temporary file named after the plugin
+(e.g. ``<config_dir>/.header_rewrite_inline_1.conf``). Temporary files
+from a previous run are removed automatically at startup.
+
+This works equally well for plugins that read YAML configuration files.
+The block scalar preserves quoting and formatting that some YAML-consuming
+plugins rely on:
+
+.. code-block:: yaml
+
+   plugins:
+     - path: txn_box.so
+       config: |
+         txn_box:
+           when: proxy-rsp
+           do:
+             - proxy-rsp-field<X-TxnBox>: "inline-config-active"
+
+.. note::
+
+   The ``config`` field and ``params`` can be used together. When both are
+   present, the temporary file path is inserted before the ``params`` entries
+   in the argument vector:
+
+   .. code-block:: yaml
+
+      plugins:
+        - path: header_rewrite.so
+          config: |
+            cond %{SEND_RESPONSE_HDR_HOOK}
+              set-header X-Source "inline"
+          params:
+            - --verbose
+
+   The plugin receives ``argv = ["header_rewrite.so",
+   "<config_dir>/.header_rewrite_inline_1.conf", "--verbose"]``.
+
+   The inline file path is always a bare positional argument at ``argv[1]``.
+   This works for plugins that take a config file as their first argument
+   (e.g., ``header_rewrite.so``, ``txn_box.so``).  Plugins that require a
+   flag before the filename (e.g., ``--config <file>``) should use ``params``
+   pointing to a separate file instead of ``config``.
+
 Configuration Variable Expansion
 ---------------------------------
 

doc/appendices/command-line/traffic_ctl.en.rst

@@ -732,6 +732,47 @@ Display the current value of a configuration record.
    Display information about the registered files in |TS|. This includes the full file path, config record name, parent config (if any)
    if needs root access and if the file is required in |TS|.
 
+.. program:: traffic_ctl config
+.. option:: convert <type> <args...>
+
+   Convert a legacy configuration file to its YAML equivalent. The conversion
+   runs locally — no running :program:`traffic_server` is required.
+
+   Supported types:
+
+   ``ssl_multicert``
+      Convert ``ssl_multicert.config`` to :file:`ssl_multicert.yaml`.
+
+      .. code-block:: bash
+
+         traffic_ctl config convert ssl_multicert ssl_multicert.config ssl_multicert.yaml
+
+   ``storage``
+      Convert ``storage.config`` and ``volume.config`` to
+      :file:`storage.yaml`.
+
+      .. code-block:: bash
+
+         traffic_ctl config convert storage storage.config volume.config storage.yaml
+
+   ``plugin_config``
+      Convert :file:`plugin.config` to :file:`plugin.yaml`.
+      Commented-out lines are converted to ``enabled: false`` entries by
+      default. Pass ``--skip-disabled`` to omit them entirely.
+
+      .. code-block:: bash
+
+         # Write to a file
+         traffic_ctl config convert plugin_config plugin.config plugin.yaml
+
+         # Preview on stdout
+         traffic_ctl config convert plugin_config plugin.config -
+
+         # Drop commented-out entries
+         traffic_ctl config convert plugin_config plugin.config plugin.yaml --skip-disabled
+
+   For all types, use ``-`` as the output file to write to stdout.
+
 .. program:: traffic_ctl config
 .. option:: ssl-multicert show [--yaml | --json]
 
@@ -993,6 +1034,36 @@ traffic_ctl plugin
 -------------------
 
 .. program:: traffic_ctl plugin
+.. option:: list
+
+   Display the globally loaded plugins and their status.  The output includes
+   the configuration source, each plugin's sequence index, path,
+   ``load_order`` (when any plugin has one), and status.
+
+   Example (with ``load_order``):
+
+   .. code-block:: bash
+
+      $ traffic_ctl plugin list
+      source: plugin.yaml
+        #  plugin                          load_order   status
+        1  certifier.so                    100          loaded
+        2  header_rewrite.so               --           loaded
+        3  debug_plugin.so                 --           disabled
+
+   Example (without ``load_order``):
+
+   .. code-block:: bash
+
+      $ traffic_ctl plugin list
+      source: plugin.yaml
+        #  plugin                          status
+        1  stats_over_http.so              loaded
+        2  header_rewrite.so               loaded
+
+   This command requires a running :program:`traffic_server` instance — it
+   communicates via JSONRPC.
+
 .. option:: msg TAG DATA
 
    :ref:`admin_plugin_send_basic_msg`

doc/release-notes/whats-new.en.rst

@@ -76,6 +76,14 @@ TS API
 Features
 --------
 
+* Add :file:`plugin.yaml`, a YAML-based replacement for :file:`plugin.config`.
+  New features include disabling plugins without deleting lines
+  (``enabled: false``), explicit ``load_order``, inline ``config`` content, and
+  startup logging. See :doc:`../admin-guide/files/plugin.yaml.en`.
+* traffic_ctl: Add ``plugin list`` to show loaded plugins and their status via
+  JSONRPC.
+* traffic_ctl: Add ``config convert plugin_config`` to migrate
+  :file:`plugin.config` to :file:`plugin.yaml`.
 * Add the ``cqssg`` log field for TLS group name logging
 * traffic_ctl: Add a new :ref:`server <traffic-control-command-server-status>` command to show some basic internal
   information

include/proxy/Plugin.h

@@ -40,6 +40,7 @@ struct PluginYAMLEntry {
   bool                     enabled{true};
   int                      load_order{-1};
   std::vector<std::string> params;
+  std::string              config_literal;
 };
 
 using PluginYAMLEntries = std::vector<PluginYAMLEntry>;
@@ -83,6 +84,7 @@ bool plugin_yaml_init(bool validateOnly = false);
 bool plugin_dso_load(const char *path, void *&handle, void *&init, std::string &error);
 
 /// Parse plugin.yaml and return sorted entries.
+/// Exposed (non-static) for unit testing.
 config::ConfigResult<PluginYAMLEntries> parse_plugin_yaml(const char *yaml_path);
 
 /** Abstract interface class for plugin based continuations.

src/config/plugin_config.cc

@@ -31,7 +31,8 @@
 namespace
 {
 
-constexpr char KEY_PLUGINS[] = "plugins";
+constexpr char                   KEY_PLUGINS[] = "plugins";
+constexpr swoc::Errata::Severity INFO_SEVERITY{0};
 
 std::vector<std::string>
 tokenize_plugin_line(std::string_view line)
@@ -117,8 +118,10 @@ PluginConfigParser::parse_legacy(std::string_view content)
   ConfigResult<PluginConfigData> result;
   std::istringstream             stream{std::string{content}};
   std::string                    line;
+  int                            line_no = 0;
 
   while (std::getline(stream, line)) {
+    ++line_no;
     std::string_view sv{line};
 
     std::size_t start = 0;
@@ -151,8 +154,8 @@ PluginConfigParser::parse_legacy(std::string_view content)
       continue;
     }
 
-    // Heuristic: a plugin line must have a .so path as first token
     if (tokens[0].find(".so") == std::string::npos) {
+      result.errata.note(INFO_SEVERITY, "skipping line {}: '{}' does not look like a plugin path (no .so)", line_no, tokens[0]);
       continue;
     }