docs - clarify gpinitsystem -O behavior (#10228)

* clarifying pg_upgrade note

* gpinitsystem -O clarification

* further reviews

gpdb-doc/dita/install_guide/init_gpdb.xml

@@ -187,7 +187,15 @@ $ gpinitsystem -c gpconfigs/gpinitsystem_config -h gpconfigs/hostfile_gpinitsyst
                 a fully redundant system (with a standby master and a <i>spread</i> mirror
                 configuration) include the <codeph>-s</codeph> and <codeph>-S</codeph> options. For
                 example:</p><codeblock>$ gpinitsystem -c gpconfigs/gpinitsystem_config -h gpconfigs/hostfile_gpinitsystem \
-  -s <varname>standby_master_hostname</varname> -S</codeblock></li>
+  -s <varname>standby_master_hostname</varname> -S</codeblock><p>During
+                a new cluster creation, you may use the <codeph><varname>-O
+                    output_configuration_file</varname></codeph> option to save the cluster
+                configuration details in a file. For
+                example:</p><codeblock>$ gpinitsystem -c gpconfigs/gpinitsystem_config -O gpconfigs/config_template </codeblock><p>This
+                output file can be edited and used at a later stage as the input file of the
+                  <codeph>-I</codeph> option, to create a new cluster or to recover from a backup.
+                See <xref href="../utility_guide/ref/gpinitsystem.xml" format="xml"
+                  >gpinitsystem</xref> for further details.</p></li>
             <li id="jm138853">The utility will verify your setup information and make sure it can
               connect to each host and access the data directories specified in your configuration.
               If all of the pre-checks are successful, the utility will prompt you to confirm your

gpdb-doc/dita/utility_guide/ref/gpinitsystem.xml

@@ -39,24 +39,17 @@
                     href="#topic1/section5" type="section" format="dita"/> for more information
                 about the configuration file. Before running this utility, make sure that you have
                 installed the Greenplum Database software on all the hosts in the array.</p>
-            <p>With the <codeph>-O <varname>output_configuration_file</varname></codeph> option,
-                    <codeph>gpinitsystem</codeph> does not create a new database instance but
-                instead writes all provided configuration information to the specified output file.
-                This file uses the <codeph>QD_PRIMARY_ARRAY</codeph> and
-                    <codeph>PRIMARY_ARRAY</codeph> parameters to define each member using its
-                hostname, port, data directory, segment prefix, segment ID, and content ID. Details
-                of the array configuration can be modified as necessary to match values available in
-                a Greenplum Database backup, or can simply be used to recreate the same cluster
-                configuration at a later time. Configuration files that use
-                    <codeph>QD_PRIMARY_ARRAY</codeph> and <codeph>PRIMARY_ARRAY</codeph> must be
-                passed into <codeph>gpinitsystem</codeph> using the <codeph>-I
-                        <varname>input_configuration_file</varname></codeph> option. See <xref
-                    href="#topic1/section5" type="section" format="dita"/> for more information.</p>
-            <p>In a Greenplum Database DBMS, each database instance (the master and all segments)
-                must be initialized across all of the hosts in the system in such a way that they
-                can all work together as a unified DBMS. The <codeph>gpinitsystem</codeph> utility
-                takes care of initializing the Greenplum master and each segment instance, and
-                configuring the system as a whole.</p>
+            <p>With the <codeph><varname>-O output_configuration_file</varname></codeph> option,
+                    <codeph>gpinitsystem</codeph> writes all provided configuration information to
+                the specified output file. This file can be used with the <codeph>-I</codeph> option
+                to create a new cluster or re-create a cluster from a backed up configuration. See
+                    <xref href="#topic1/section5" type="section" format="dita"/> for more
+                information. </p>
+            <p>In a Greenplum Database DBMS, each database instance (the master instance and all
+                segment instances) must be initialized across all of the hosts in the system in such
+                a way that they can all work together as a unified DBMS. The
+                    <codeph>gpinitsystem</codeph> utility takes care of initializing the Greenplum
+                master and each segment instance, and configuring the system as a whole.</p>
             <p>Before running <codeph>gpinitsystem</codeph>, you must set the
                     <codeph>$GPHOME</codeph> environment variable to point to the location of your
                 Greenplum Database installation on the master host and exchange SSH keys between all
@@ -123,12 +116,14 @@
                 <plentry>
                     <pt>-I <varname>input_configuration_file</varname></pt>
                     <pd>The full path and filename of an input configuration file, which defines the
-                        Greenplum Database members and segments using the
-                            <codeph>QD_PRIMARY_ARRAY</codeph> and <codeph>PRIMARY_ARRAY</codeph>
+                        Greenplum Database host systems, the master instance and segment instances
+                        on the hosts, using the <codeph>QD_PRIMARY_ARRAY</codeph>,
+                            <codeph>PRIMARY_ARRAY</codeph>, and <codeph>MIRROR_ARRAY</codeph>
                         parameters. The input configuration file is typically created by using
-                        gpinitsystem with the <codeph>-O
-                                <varname>output_configuration_file</varname></codeph> option. You
-                        must provide either the <codeph>-c
+                            <codeph>gpinitsystem</codeph> with the <codeph>-O
+                                <varname>output_configuration_file</varname></codeph> option. Edit
+                        those parameters in order to initialize a new cluster or re-create a cluster
+                        from a backed up configuration. You must provide either the <codeph>-c
                                 <varname>cluster_configuration_file</varname></codeph> option or the
                             <codeph>-I <varname>input_configuration_file</varname></codeph> option
                         to <codeph>gpinitsystem</codeph>. </pd>
@@ -218,17 +213,17 @@
                     <pd>Sets the maximum number of client connections allowed to the master. The
                         default is 250.</pd>
                 </plentry>
-                <plentry>
+                <plentry id="output_config_file">
                     <pt>-O <varname>output_configuration_file</varname></pt>
-                    <pd>When used with the <codeph>-O</codeph> option, <codeph>gpinitsystem</codeph>
-                        does not create a new Greenplum Database cluster but instead writes the
-                        supplied cluster configuration information to the specified
-                                <codeph><varname>output_configuration_file</varname></codeph>. This
-                        file defines Greenplum Database members and segments using the
+                    <pd>Optional, used during new cluster initialization. This option writes the
+                            <varname>cluster_configuration_file</varname> information (used with -c)
+                        to the specified <varname>output_configuration_file</varname>. This file
+                        defines the Greenplum Database members using the
                             <codeph>QD_PRIMARY_ARRAY</codeph>, <codeph>PRIMARY_ARRAY</codeph>, and
-                            <codeph>MIRROR_ARRAY</codeph> parameters, and can be later used with
-                            <codeph>-I <varname>input_configuration_file</varname></codeph> to
-                        initialize a new cluster.</pd>
+                            <codeph>MIRROR_ARRAY</codeph> parameters. Use this file as a template
+                        for the <codeph>-I </codeph><varname>input_configuration_file</varname>
+                        option.  See <xref href="#topic1/section6" format="dita">Examples</xref> for
+                        more information. </pd>
                 </plentry>
                 <plentry>
                     <pt>-p <varname>postgresql_conf_param_file</varname></pt>
@@ -327,16 +322,16 @@ MIRROR_PORT_BASE = 7000</codeblock>
             <parml>
                 <plentry>
                     <pt>ARRAY_NAME</pt>
-                    <pd><b>Required.</b> A name for the array you are configuring. You can use any
+                    <pd><b>Required.</b> A name for the cluster you are configuring. You can use any
                         name you like. Enclose the name in quotes if the name contains spaces.</pd>
                 </plentry>
                 <plentry>
                     <pt>MACHINE_LIST_FILE</pt>
                     <pd><b>Optional.</b> Can be used in place of the <codeph>-h</codeph> option.
-                        This specifies the file that contains the list of segment host address names
-                        that comprise the Greenplum Database system. The master host is assumed to
-                        be the host from which you are running the utility and should not be
-                        included in this file. If your segment hosts have multiple network
+                        This specifies the file that contains the list of the segment host address
+                        names that comprise the Greenplum Database system. The master host is
+                        assumed to be the host from which you are running the utility and should not
+                        be included in this file. If your segment hosts have multiple network
                         interfaces, then this file would include all addresses for the host. Give
                         the absolute path to the file.</pd>
                 </plentry>
@@ -455,10 +450,17 @@ MIRROR_PORT_BASE = 7000</codeblock>
                 </plentry>
                 <plentry>
                     <pt>QD_PRIMARY_ARRAY, PRIMARY_ARRAY, MIRROR_ARRAY</pt>
-                    <pd>These parameters specify the Greenplum Database master host, the primary
-                        segment, and the mirror segment hosts respectively. They can only be
-                        specified in an input configuration file using the
+                    <pd><b>Required</b> when using <codeph>input_configuration file</codeph> with
+                            <codeph>-I</codeph> option. These parameters specify the Greenplum
+                        Database master host, the primary segment, and the mirror segment hosts
+                        respectively. During new cluster initialization, use the
                             <codeph>gpinitsystem</codeph>
+                        <codeph>-O <varname>output_configuration_file</varname></codeph> to populate
+                            <codeph>QD_PRIMARY_ARRAY</codeph>, <codeph>PRIMARY_ARRAY</codeph>,
+                            <codeph>MIRROR_ARRAY</codeph>. </pd>
+                    <pd>To initialize a new cluster or re-create a cluster from a backed up
+                        configuration, edit these values in the input configuration file used with
+                        the <codeph>gpinitsystem</codeph>
                         <codeph>-I <varname>input_configuration_file</varname></codeph> option. Use
                         one of the following formats to specify the host
                         information:<codeblock><varname>hostname</varname>~<varname>address</varname>~<varname>port</varname>~<varname>data_directory</varname>/<varname>seg_prefix&lt;segment_id></varname>~<varname>dbid</varname>~<varname>content_id</varname></codeblock>or
@@ -481,13 +483,8 @@ declare -a MIRROR_ARRAY=(
 localhost~127.0.0.1~50000~/gpmirror1/gpsne0~4~0~51000
 localhost~127.0.0.1~50001~/gpmirror2/gpsne1~5~1~51001 
 )</codeblock></pd>
-                    <pd>You can use the <codeph>gpinitsystem</codeph>
-                        <codeph>-O <varname>output_configuration_file</varname></codeph> to populate
-                            <codeph>QD_PRIMARY_ARRAY</codeph>, <codeph>PRIMARY_ARRAY</codeph>,
-                            <codeph>MIRROR_ARRAY</codeph> using the hosts, data directories, segment
-                        prefix, and base port values that you provide to the command. For recovery
-                        purposes, you can edit the segment and content IDs to match the values of an
-                        existing Greenplum Database backup.</pd>
+                    <pd>For recovery purposes, you can edit the segment and content IDs to match the
+                        values of an existing Greenplum Database backup.</pd>
                 </plentry>
                 <plentry>
                     <pt>HEAP_CHECKSUM</pt>
@@ -522,29 +519,43 @@ localhost~127.0.0.1~50001~/gpmirror2/gpsne1~5~1~51001
         </section>
         <section id="section6">
             <title>Examples</title>
-            <p>Initialize a Greenplum Database array by supplying a cluster configuration file and a
-                segment host address file, and set up a spread mirroring
+            <p>Initialize a Greenplum Database system by supplying a cluster configuration file and
+                a segment host address file, and set up a spread mirroring
                     (<codeph>--mirror-mode=spread</codeph>) configuration:</p>
             <codeblock>$ gpinitsystem -c gpinitsystem_config -h hostfile_gpinitsystem --mirror-mode=spread</codeblock>
-            <p>Initialize a Greenplum Database array and set the superuser remote password:</p>
+            <p>Initialize a Greenplum Database system and set the superuser remote password:</p>
             <codeblock>$ gpinitsystem -c gpinitsystem_config -h hostfile_gpinitsystem --su-password=mypassword</codeblock>
-            <p>Initialize a Greenplum Database array with an optional standby master host:</p>
+            <p>Initialize a Greenplum Database system with an optional standby master host:</p>
             <codeblock>$ gpinitsystem -c gpinitsystem_config -h hostfile_gpinitsystem -s host09</codeblock>
-            <p>Instead of initializing a Greenplum Database array, write the provided configuration
-                to an output file. The output file uses the <codeph>QD_PRIMARY_ARRAY</codeph> and
+            <p>Initialize a Greenplum Database system and write the provided configuration to an
+                output file, for example <codeph>cluster_init.config</codeph>:</p>
+            <codeblock>$ gpinitsystem -c gpinitsystem_config -h hostfile_gpinitsystem -O cluster_init.config</codeblock>
+            <p>The output file uses the <codeph>QD_PRIMARY_ARRAY</codeph> and
                     <codeph>PRIMARY_ARRAY</codeph> parameters to define master and segment
                 hosts:</p>
-            <codeblock>$ gpinitsystem -c gpinitsystem_config -h hostfile_gpinitsystem --mirror-mode=spread -O cluster_init.config</codeblock>
+            <codeblock>ARRAY_NAME="Greenplum Data Platform"
+TRUSTED_SHELL=ssh
+CHECK_POINT_SEGMENTS=8
+ENCODING=UNICODE
+SEG_PREFIX=gpseg
+HEAP_CHECKSUM=on
+HBA_HOSTNAMES=0
+QD_PRIMARY_ARRAY=mdw~mwd.local~5433~/data/master1/gpseg-1~1~-1
+declare -a PRIMARY_ARRAY=(
+mwd~mwd.local~6001~/data/primary1/gpseg0~2~0
+)
+declare -a MIRROR_ARRAY=(
+mwd~mwd.local~7001~/data/mirror1/gpseg0~3~0
+)</codeblock>
             <p>Initialize a Greenplum Database using an input configuration file (a file that
-                defines the Greenplum Database array) using <codeph>QD_PRIMARY_ARRAY</codeph> and
+                defines the Greenplum Database cluster) using <codeph>QD_PRIMARY_ARRAY</codeph> and
                     <codeph>PRIMARY_ARRAY</codeph> parameters:</p>
             <codeblock>$ gpinitsystem -I cluster_init.config</codeblock>
         </section>
-        <section id="section7">
-            <title>See Also</title>
-            <p><codeph><xref href="./gpssh-exkeys.xml#topic1" type="topic" format="dita"/></codeph>,
-                        <codeph><xref href="gpdeletesystem.xml#topic1" type="topic" format="dita"
-                    /></codeph></p>
-        </section>
+        <section id="section7"><title>See Also</title><codeph><xref href="./gpssh-exkeys.xml#topic1"
+                    type="topic" format="dita"/></codeph>, <codeph><xref
+                    href="gpdeletesystem.xml#topic1" type="topic" format="dita"/></codeph>, <xref
+                href="../../install_guide/init_gpdb.xml" format="xml">Initializing Greenplum
+                Database</xref>.</section>
     </body>
 </topic>