From 78b45a7e29635a54427f976d318e56356b700f48 Mon Sep 17 00:00:00 2001
From: Robert Haas <rhaas@postgresql.org>
Date: Mon, 27 Jul 2026 09:22:33 -0400
Subject: [PATCH v1 7/8] Document that pg_ctl -o and pg_upgrade -o/-O use the
 shell.

Including shell metacharacters in the arguments to these flags could
cause various sorts of breakage. As a corollary, untrusted users
lacking shell access should not be permitted to set the arguments to
these options to arbitrary values. The details vary by platform and by
whether or not you're running a version of PostgreSQL that includes
recent fixes in this area, so just document the issue in general
without burdening the reader with all of the specifics.

Note that the design of these options intrinsically presumes
interpretation by the shell, and therefore the fact that the shell is
invoked does not seem to be a bug. Indeed, we document usage patterns
that rely on shell interpretation for word-splitting, and it seems
very likely that some users have working command lines that rely on
the details of the shell's quoting behavior, which we should be
careful not to break without due consideration.  In future releases,
we might want to introduce an alternate, or replacement, mechanism
that does not use the shell, but for now, just document how things
work today.

Backpatch-through: 14
---
 doc/src/sgml/ref/pg_ctl-ref.sgml |  5 ++++-
 doc/src/sgml/ref/pgupgrade.sgml  | 20 ++++++++++++++------
 2 files changed, 18 insertions(+), 7 deletions(-)

diff --git a/doc/src/sgml/ref/pg_ctl-ref.sgml b/doc/src/sgml/ref/pg_ctl-ref.sgml
index b762b002c02..e0b3593756f 100644
--- a/doc/src/sgml/ref/pg_ctl-ref.sgml
+++ b/doc/src/sgml/ref/pg_ctl-ref.sgml
@@ -328,7 +328,10 @@ PostgreSQL documentation
         Specifies options to be passed directly to the
         <command>postgres</command> command.
         <option>-o</option> can be specified multiple times, with all the given
-        options being passed through.
+        options being passed through. Options are passed via the shell, so that
+        multiple options, or options with their arguments, can be passed together;
+        however, this also means including shell metacharacters in the argument
+        to this option can have undesirable effects.
        </para>
        <para>
         The <replaceable>options</replaceable> should usually be surrounded by single or
diff --git a/doc/src/sgml/ref/pgupgrade.sgml b/doc/src/sgml/ref/pgupgrade.sgml
index e4e8c02e6d6..b60e442a85c 100644
--- a/doc/src/sgml/ref/pgupgrade.sgml
+++ b/doc/src/sgml/ref/pgupgrade.sgml
@@ -156,17 +156,25 @@ PostgreSQL documentation
      <varlistentry>
       <term><option>-o</option> <replaceable class="parameter">options</replaceable></term>
       <term><option>--old-options</option> <replaceable class="parameter">options</replaceable></term>
-      <listitem><para>options to be passed directly to the
-      old <command>postgres</command> command;  multiple
-      option invocations are appended</para></listitem>
+      <listitem><para>
+        Options to be passed directly to the old <command>postgres</command>
+        command; multiple option invocations are appended.  Options are passed via
+        the shell, so that multiple options, or options with their arguments, can
+        be passed together; however, this also means including shell metacharacters
+        in the argument to this option can have undesirable effects.
+      </para></listitem>
      </varlistentry>
 
      <varlistentry>
       <term><option>-O</option> <replaceable class="parameter">options</replaceable></term>
       <term><option>--new-options</option> <replaceable class="parameter">options</replaceable></term>
-      <listitem><para>options to be passed directly to the
-      new <command>postgres</command> command;  multiple
-      option invocations are appended</para></listitem>
+      <listitem><para>
+        Options to be passed directly to the new <command>postgres</command>
+        command; multiple option invocations are appended.  Options are passed via
+        the shell, so that multiple options, or options with their arguments, can
+        be passed together; however, this also means including shell metacharacters
+        in the argument to this option can have undesirable effects.
+      </para></listitem>
      </varlistentry>
 
      <varlistentry>
-- 
2.50.1 (Apple Git-155)

