Add --cmd option.

Allows users to provide an executable to be used when pgbackrest generates command strings that expect to invoke pgbackrest. These generated commands are written to files by pgbackrest, e.g. recovery.conf.

doc/xml/release.xml

@@ -16,6 +16,22 @@
     <release-list>
         <release date="XXXX-XX-XX" version="2.37dev" title="UNDER DEVELOPMENT">
             <release-core-list>
+                <release-feature-list>
+                    <release-item>
+                        <github-issue id="1537"/>
+                        <github-pull-request id="1540"/>
+
+                        <release-item-contributor-list>
+                            <release-item-ideator id="virgile.crevon"/>
+                            <release-item-contributor id="reid.thompson"/>
+                            <release-item-reviewer id="stefan.fercot"/>
+                            <release-item-reviewer id="david.steele"/>
+                        </release-item-contributor-list>
+
+                        <p>Add <br-option>--cmd</br-option> option.</p>
+                    </release-item>
+                </release-feature-list>
+
                 <release-development-list>
                     <release-item>
                         <github-pull-request id="1549"/>
@@ -10925,6 +10941,11 @@
             <contributor-id type="github">vitabaks</contributor-id>
         </contributor>
 
+        <contributor id="virgile.crevon">
+            <contributor-name-display>Virgile CREVON</contributor-name-display>
+            <contributor-id type="github">collectionneurfou</contributor-id>
+        </contributor>
+
         <contributor id="vthriller">
             <contributor-name-display>vthriller</contributor-name-display>
             <contributor-id type="github">vthriller</contributor-id>

src/build/config/config.yaml

@@ -614,10 +614,10 @@ option:
       stanza-upgrade: {}
       verify: {}
 
-  cmd-ssh:
+  cmd:
     section: global
     type: string
-    default: ssh
+    required: false
     command:
       archive-get: {}
       archive-push: {}
@@ -639,6 +639,11 @@ option:
       main: {}
       local: {}
 
+  cmd-ssh:
+    inherit: cmd
+    required: true
+    default: ssh
+
   # Option is deprecated and should not be referenced outside of cfgLoadUpdateOption()
   compress:
     section: global

src/build/help/help.xml

@@ -140,6 +140,19 @@
                         <example>32K</example>
                     </config-key>
 
+                    <!-- CONFIG - GENERAL SECTION - CMD KEY -->
+                    <config-key id="cmd" name="{[project]} Command">
+                        <summary><backrest/> command.</summary>
+
+                        <text>
+                            <p><backrest/> may generate a command string, e.g. when the <cmd>restore</cmd> command generates the <pg-setting>restore_command</pg-setting> setting. The command used to run the <backrest/> process will be used in this case unless the <br-option>cmd</br-option> option is provided.</p>
+
+                            <admonition type="caution">Wrapping the <backrest/> command may cause unpredictable behavior and is not recommended.</admonition>
+                        </text>
+
+                        <example>/var/lib/pgsql/bin/pgbackrest_wrapper.sh</example>
+                    </config-key>
+
                     <!-- CONFIG - GENERAL SECTION - CMD-SSH KEY -->
                     <config-key id="cmd-ssh" name="SSH Client Command">
                         <summary>SSH client command.</summary>

src/command/restore/restore.c

@@ -1580,12 +1580,13 @@ restoreRecoveryOption(unsigned int pgVersion)
             kvPut(optionReplace, VARSTRDEF(CFGOPT_LOG_SUBPROCESS), NULL);
             kvPut(optionReplace, VARSTRDEF(CFGOPT_LOG_TIMESTAMP), NULL);
             kvPut(optionReplace, VARSTRDEF(CFGOPT_PROCESS_MAX), NULL);
+            kvPut(optionReplace, VARSTRDEF(CFGOPT_CMD), NULL);
 
             kvPut(
                 result, VARSTRZ(RESTORE_COMMAND),
                 VARSTR(
                     strNewFmt(
-                        "%s %s %%f \"%%p\"", strZ(cfgExe()),
+                        "%s %s %%f \"%%p\"", strZ(cfgOptionStr(cfgOptCmd)),
                         strZ(strLstJoin(cfgExecParam(cfgCmdArchiveGet, cfgCmdRoleMain, optionReplace, true, true), " ")))));
         }
 

src/config/config.auto.h

@@ -55,6 +55,7 @@ Option constants
 #define CFGOPT_BUFFER_SIZE                                          "buffer-size"
 #define CFGOPT_CHECKSUM_PAGE                                        "checksum-page"
 #define CFGOPT_CIPHER_PASS                                          "cipher-pass"
+#define CFGOPT_CMD                                                  "cmd"
 #define CFGOPT_CMD_SSH                                              "cmd-ssh"
 #define CFGOPT_COMPRESS                                             "compress"
 #define CFGOPT_COMPRESS_LEVEL                                       "compress-level"
@@ -125,7 +126,7 @@ Option constants
 #define CFGOPT_TLS_SERVER_PORT                                      "tls-server-port"
 #define CFGOPT_TYPE                                                 "type"
 
-#define CFG_OPTION_TOTAL                                            148
+#define CFG_OPTION_TOTAL                                            149
 
 /***********************************************************************************************************************************
 Option value constants
@@ -364,6 +365,7 @@ typedef enum
     cfgOptBufferSize,
     cfgOptChecksumPage,
     cfgOptCipherPass,
+    cfgOptCmd,
     cfgOptCmdSsh,
     cfgOptCompress,
     cfgOptCompressLevel,

src/config/load.c

@@ -107,6 +107,10 @@ cfgLoadUpdateOption(void)
         }
     }
 
+    // Set default for cmd
+    if (cfgOptionValid(cfgOptCmd))
+        cfgOptionDefaultSet(cfgOptCmd, VARSTR(cfgExe()));
+
     // Set default for repo-host-cmd
     if (cfgOptionValid(cfgOptRepoHostCmd))
         cfgOptionDefaultSet(cfgOptRepoHostCmd, VARSTR(cfgExe()));

src/config/parse.auto.c

@@ -1175,6 +1175,50 @@ static const ParseRuleOption parseRuleOption[CFG_OPTION_TOTAL] =
         ),
     ),
 
+    // -----------------------------------------------------------------------------------------------------------------------------
+    PARSE_RULE_OPTION
+    (
+        PARSE_RULE_OPTION_NAME("cmd"),
+        PARSE_RULE_OPTION_TYPE(cfgOptTypeString),
+        PARSE_RULE_OPTION_RESET(true),
+        PARSE_RULE_OPTION_REQUIRED(false),
+        PARSE_RULE_OPTION_SECTION(cfgSectionGlobal),
+
+        PARSE_RULE_OPTION_COMMAND_ROLE_MAIN_VALID_LIST
+        (
+            PARSE_RULE_OPTION_COMMAND(cfgCmdArchiveGet)
+            PARSE_RULE_OPTION_COMMAND(cfgCmdArchivePush)
+            PARSE_RULE_OPTION_COMMAND(cfgCmdBackup)
+            PARSE_RULE_OPTION_COMMAND(cfgCmdCheck)
+            PARSE_RULE_OPTION_COMMAND(cfgCmdInfo)
+            PARSE_RULE_OPTION_COMMAND(cfgCmdRepoCreate)
+            PARSE_RULE_OPTION_COMMAND(cfgCmdRepoGet)
+            PARSE_RULE_OPTION_COMMAND(cfgCmdRepoLs)
+            PARSE_RULE_OPTION_COMMAND(cfgCmdRepoPut)
+            PARSE_RULE_OPTION_COMMAND(cfgCmdRepoRm)
+            PARSE_RULE_OPTION_COMMAND(cfgCmdRestore)
+            PARSE_RULE_OPTION_COMMAND(cfgCmdStanzaCreate)
+            PARSE_RULE_OPTION_COMMAND(cfgCmdStanzaDelete)
+            PARSE_RULE_OPTION_COMMAND(cfgCmdStanzaUpgrade)
+            PARSE_RULE_OPTION_COMMAND(cfgCmdVerify)
+        ),
+
+        PARSE_RULE_OPTION_COMMAND_ROLE_ASYNC_VALID_LIST
+        (
+            PARSE_RULE_OPTION_COMMAND(cfgCmdArchiveGet)
+            PARSE_RULE_OPTION_COMMAND(cfgCmdArchivePush)
+        ),
+
+        PARSE_RULE_OPTION_COMMAND_ROLE_LOCAL_VALID_LIST
+        (
+            PARSE_RULE_OPTION_COMMAND(cfgCmdArchiveGet)
+            PARSE_RULE_OPTION_COMMAND(cfgCmdArchivePush)
+            PARSE_RULE_OPTION_COMMAND(cfgCmdBackup)
+            PARSE_RULE_OPTION_COMMAND(cfgCmdRestore)
+            PARSE_RULE_OPTION_COMMAND(cfgCmdVerify)
+        ),
+    ),
+
     // -----------------------------------------------------------------------------------------------------------------------------
     PARSE_RULE_OPTION
     (
@@ -8952,6 +8996,7 @@ static const ConfigOption optionResolveOrder[] =
     cfgOptBufferSize,
     cfgOptChecksumPage,
     cfgOptCipherPass,
+    cfgOptCmd,
     cfgOptCmdSsh,
     cfgOptCompress,
     cfgOptCompressLevel,

test/src/module/command/helpTest.c

@@ -223,6 +223,8 @@ testRun(void)
             "\n"
             "  --buffer-size                    buffer size for I/O operations\n"
             "                                   [current=32768, default=1048576]\n"
+            "  --cmd                            pgBackRest command\n"
+            "                                   [default=/path/to/pgbackrest]\n"
             "  --cmd-ssh                        SSH client command [default=ssh]\n"
             "  --compress-level-network         network compression level [default=3]\n"
             "  --config                         pgBackRest configuration file\n"

test/src/module/command/restoreTest.c

@@ -1584,6 +1584,20 @@ testRun(void)
                 " --repo1-path=/repo --stanza=test1 archive-get %f \"%p\"'\n",
             "check recovery options");
 
+        // -------------------------------------------------------------------------------------------------------------------------
+        TEST_TITLE("user-specified cmd");
+
+        argList = strLstDup(argBaseList);
+        hrnCfgArgRawZ(argList, cfgOptCmd, "/usr/local/bin/pg_wrapper.sh");
+        HRN_CFG_LOAD(cfgCmdRestore, argList);
+
+        TEST_RESULT_STR_Z(
+            restoreRecoveryConf(PG_VERSION_94, restoreLabel),
+            RECOVERY_SETTING_HEADER
+            "restore_command = '/usr/local/bin/pg_wrapper.sh --lock-path=" HRN_PATH "/lock --log-path=" HRN_PATH " --pg1-path=/pg"
+                " --repo1-path=/repo --stanza=test1 archive-get %f \"%p\"'\n",
+            "restore_command invokes /usr/local/bin/pg_wrapper.sh per --cmd option");
+
         // -------------------------------------------------------------------------------------------------------------------------
         TEST_TITLE("override restore_command");
 

test/src/module/config/parseTest.c

@@ -1768,6 +1768,35 @@ testRun(void)
             configParse(storageTest, strLstSize(argList), strLstPtr(argList), false), OptionInvalidError,
             "key/value 'a' not valid for 'recovery-option' option");
 
+        // -------------------------------------------------------------------------------------------------------------------------
+        TEST_TITLE("option cmd");
+
+        argList = strLstNew();
+        strLstAddZ(argList, TEST_BACKREST_EXE);
+        strLstAddZ(argList, TEST_COMMAND_BACKUP);
+        hrnCfgArgRawZ(argList, cfgOptStanza, "db");
+        hrnCfgArgKeyRawZ(argList, cfgOptPgPath, 1, "/path/to/1");
+        TEST_RESULT_VOID(configParse(storageTest, strLstSize(argList), strLstPtr(argList), true), "load local config");
+
+        TEST_RESULT_STR_Z(cfgExe(), "pgbackrest", "--cmd not provided; cfgExe() returns " TEST_BACKREST_EXE);
+
+        argList = strLstNew();
+        hrnCfgArgRawZ(argList, cfgOptStanza, "db");
+        hrnCfgArgKeyRawZ(argList, cfgOptPgPath, 1, "/path/to/1");
+        HRN_CFG_LOAD(cfgCmdRestore, argList);
+
+        TEST_RESULT_STR_Z(cfgOptionStr(cfgOptCmd), TEST_PROJECT_EXE , "--cmd not provided; cmd is defaulted to " TEST_PROJECT_EXE);
+
+        argList = strLstNew();
+        strLstAddZ(argList, TEST_BACKREST_EXE);
+        strLstAddZ(argList, TEST_COMMAND_BACKUP);
+        hrnCfgArgRawZ(argList, cfgOptStanza, "db");
+        hrnCfgArgKeyRawZ(argList, cfgOptPgPath, 1, "/path/to/1");
+        hrnCfgArgRawZ(argList, cfgOptCmd, "pgbackrest_wrapper.sh");
+        TEST_RESULT_VOID(configParse(storageTest, strLstSize(argList), strLstPtr(argList), true), "load local config");
+
+        TEST_RESULT_STR_Z(cfgOptionStr(cfgOptCmd), "pgbackrest_wrapper.sh", "--cmd provided; cmd is returned as pgbackrest_wrapper.sh");
+
         // -------------------------------------------------------------------------------------------------------------------------
         TEST_TITLE("default job retry and valid duplicate options");