docs - update utility docs with IP/hostname information. (#10379)

* docs - update utility docs with IP/hostname information.

Add information to gpinitsystem, gpaddmirrors, and gpexpand ref. docs
--Information about using hostnames vs. IP addresses
--Information about configuring hosts that are configured with mulitple NICs

Also updated some examples in gpinitsystem

* docs - review comment updates. Add more information from dev.

* docs - change examples to show valid configurations that support failorver.
Also fix typos and minor edits.

* docs - updates based on review comments.

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

@@ -106,18 +106,22 @@ Enter mirror segment data directory location 2 of 2 &gt; /gpdb/m2</codeblock>
                 <plentry>
                     <pt>-i <varname>mirror_config_file</varname></pt>
                     <pd>A configuration file containing one line for each mirror segment you want to
-                        create. You must have one mirror segment listed for each primary segment in
-                        the system. The format of this file is as follows (as per attributes in the
-                            <codeph>gp_segment_configuration</codeph> catalog table):</pd>
+                        create. You must have one mirror segment instance listed for each primary
+                        segment in the system. The format of this file is as follows (as per
+                        attributes in the <codeph><xref
+                                href="../../ref_guide/system_catalogs/gp_segment_configuration.xml"
+                                >gp_segment_configuration</xref></codeph> catalog table):</pd>
                     <pd>
                         <codeblock>&lt;contentID>|&lt;address>|&lt;port>|&lt;data_dir></codeblock>
                     </pd>
                     <pd>
                         <p>Where <codeph>&lt;contentID></codeph> is the segment instance content ID,
-                                <codeph>&lt;address></codeph> is the host name or IP address of the
+                                <codeph>&lt;address></codeph> is the hostname or IP address of the
                             segment host, <codeph>&lt;port></codeph> is the communication port, and
                                 <codeph>&lt;data_dir></codeph> is the segment instance data
-                            directory.</p>
+                            directory. For information about using a hostname or IP address, see
+                                <xref href="#topic1/host_ip" format="dita"/>. Also, see <xref
+                                href="#topic1/multi_nic" format="dita"/>.</p>
                     </pd>
                 </plentry>
                 <plentry>
@@ -180,12 +184,69 @@ Enter mirror segment data directory location 2 of 2 &gt; /gpdb/m2</codeblock>
                 </plentry>
             </parml>
         </section>
+        <section id="host_ip">
+            <title>Specifying Hosts using Hostnames or IP Addresses</title>
+            <p>When specifying a mirroring configuration using the <codeph>gpaddmirrors</codeph>
+                option <codeph>-i</codeph>, you can specify either a hostname or an IP address for
+                the &lt;address> value. <ul id="ul_zsd_cmh_dmb">
+                    <li>If you specify a hostname, the resolution of the hostname to an IP address
+                        should be done locally for security. For example, you should use entries in
+                        a local <codeph>/etc/hosts</codeph> file to map the hostname to an IP
+                        address. The resolution of a hostname to an IP address should not be
+                        performed by an external service such as a public DNS server. You must stop
+                        the Greenplum system before you change the mapping of a hostname to a
+                        different IP address.</li>
+                    <li>If you specify an IP address, the address should not be changed after the
+                        initial configuration. When segment mirroring is enabled, replication from
+                        the primary to the mirror segment will fail if the IP address changes from
+                        the configured value. For this reason, you should use a hostname when
+                        enabling mirroring using the <codeph>-i</codeph> option unless you have a
+                        specific requirement to use IP addresses.</li>
+                </ul></p>
+            <p>When enabling a mirroring configuration that adds hosts to the Greenplum system,
+                    <codeph>gpaddmirrors</codeph> populates the <codeph><xref
+                        href="../../ref_guide/system_catalogs/gp_segment_configuration.xml"
+                        >gp_segment_configuration</xref></codeph> catalog table with the mirror
+                segment instance information. Greenplum Database uses the <varname>address</varname>
+                value of the <codeph>gp_segment_configuration</codeph> catalog table when looking up
+                host systems for Greenplum interconnect (internal) communication between the master
+                and segment instances and between segment instances, and for other internal
+                communication.</p>
+        </section>
+        <section id="multi_nic">
+            <title>Using Host Systems with Multiple NICs</title>
+            <p>If hosts systems are configured with multiple NICs, you can initialize a Greenplum
+                Database system to use each NIC as a Greenplum host system. You must ensure that the
+                host systems are configured with sufficient resources to support all the segment
+                instances being added to the host. Also, if you enable segment mirroring, you must
+                ensure that the Greenplum system configuration supports failover if a host system
+                fails. For information about Greenplum Database mirroring schemes, see <xref
+                    href="../../best_practices/ha.xml#topic_ngz_qf4_tt"/>.</p>
+            <p>For example, this is a segment instance configuration for a simple Greenplum system.
+                The segment host <codeph>gp6m</codeph> is configured with two NICs,
+                    <codeph>gp6m-1</codeph> and <codeph>gp6m-2</codeph>, where the Greenplum
+                Database system uses <codeph>gp6m-1</codeph> for the master segment and
+                    <codeph>gp6m-2</codeph> for segment instances. </p>
+            <codeblock>select content, role, port, hostname, address from gp_segment_configuration ;
+
+ content | role | port  | hostname | address
+---------+------+-------+----------+----------
+      -1 | p    |  5432 | gp6m     | gp6m-1
+       0 | p    | 40000 | gp6m     | gp6m-2
+       0 | m    | 50000 | gp6s     | gp6s
+       1 | p    | 40000 | gp6s     | gp6s
+       1 | m    | 50000 | gp6m     | gp6m-2
+(5 rows) </codeblock>
+        </section>
         <section id="section5">
             <title>Examples</title>
             <p>Add mirroring to an existing Greenplum Database system using the same set of hosts as
                 your primary data. Calculate the mirror database ports by adding 100 to the current
                 primary segment port numbers:</p>
             <codeblock>$ gpaddmirrors -p 100</codeblock>
+            <p>Generate a sample mirror configuration file with the <codeph>-o</codeph> option to
+                use with <codeph>gpaddmirrors -i</codeph>:</p>
+            <codeblock>$ gpaddmirrors -o /home/gpadmin/sample_mirror_config</codeblock>
             <p>Add mirroring to an existing Greenplum Database system using a different set of hosts
                 from your primary data:</p>
             <codeblock>$ gpaddmirrors -i mirror_config_file</codeblock>
@@ -194,9 +255,6 @@ Enter mirror segment data directory location 2 of 2 &gt; /gpdb/m2</codeblock>
 1|sdw1-2|52002|/gpdata/m2/gp1
 2|sdw2-1|52001|/gpdata/m1/gp2
 3|sdw2-2|52002|/gpdata/m2/gp3</codeblock>
-            <p>Generate a sample mirror configuration file with the <codeph>-o</codeph> option to
-                use with <codeph>gpaddmirrors -i</codeph>:</p>
-            <codeblock>$ gpaddmirrors -o /home/gpadmin/sample_mirror_config</codeblock>
         </section>
         <section id="section6">
             <title>See Also</title>

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

@@ -39,11 +39,10 @@
         <li>When redistributing data, Greenplum Database must be running in production mode.
           Greenplum Database cannot be running in restricted mode or in master mode. The
             <codeph>gpstart</codeph> options <codeph>-R</codeph> or <codeph>-m</codeph> cannot be
-          specified to start Greenplum Database. </li>      
+          specified to start Greenplum Database. </li>
       </ul>
       <note>These utilities cannot be run while <codeph>gpexpand</codeph> is performing segment
-        initialization.
-        <ul id="ul_c3w_wdp_lgb">
+        initialization. <ul id="ul_c3w_wdp_lgb">
           <li><codeph>gpbackup</codeph></li>
           <li><codeph>gpcheckcat</codeph></li>
           <li><codeph>gpconfig</codeph></li>
@@ -75,8 +74,8 @@
       </ul>
       <p>In the table data redistribution phase, <codeph>gpexpand</codeph> redistributes table data
         to rebalance the data across the old and new segment instances.</p>
-      <note>Data redistribution should be performed during low-use hours. Redistribution can be divided
-        into batches over an extended period.</note>
+      <note>Data redistribution should be performed during low-use hours. Redistribution can be
+        divided into batches over an extended period.</note>
       <p>To begin the redistribution phase, run <codeph>gpexpand</codeph> with either the
           <codeph>-d</codeph> (duration) or <codeph>-e</codeph> (end time) options, or with no
         options. If you specify an end time or duration, then the utility redistributes tables in
@@ -142,6 +141,8 @@
               number to the host name. For example, <codeph>sdw1-1</codeph> and
                 <codeph>sdw1-2</codeph> are the two interface names for host <codeph>sdw1</codeph>.
             </note></pd>
+          <pd>For information about using a hostname or IP address, see <xref href="#topic1/host_ip"
+              format="dita"/>. Also, see <xref href="#topic1/multi_nic" format="dita"/>.</pd>
         </plentry>
         <plentry>
           <pt>-i | --input <varname>input_file</varname></pt>
@@ -199,6 +200,48 @@
         </plentry>
       </parml>
     </section>
+    <section id="host_ip">
+      <title>Specifying Hosts using Hostnames or IP Addresses</title>
+      <p>When expanding a Greenplum Database system, you can specify either a hostname or an IP
+        address for the value. <ul id="ul_zsd_cmh_dmb">
+          <li>If you specify a hostname, the resolution of the hostname to an IP address should be
+            done locally for security. For example, you should use entries in a local
+              <codeph>/etc/hosts</codeph> file to map a hostname to an IP address. The resolution of
+            a hostname to an IP address should not be performed by an external service such as a
+            public DNS server. You must stop the Greenplum system before you change the mapping of a
+            hostname to a different IP address.</li>
+          <li>If you specify an IP address, the address should not be changed after the initial
+            configuration. When segment mirroring is enabled, replication from the primary to the
+            mirror segment will fail if the IP address changes from the configured value. For this
+            reason, you should use a hostname when expanding a Greenplum Database system unless you
+            have a specific requirement to use IP addresses.</li>
+        </ul></p>
+      <p>When expanding a Greenplum system, <codeph>gpexpand</codeph> populates <codeph><xref
+            href="../../ref_guide/system_catalogs/gp_segment_configuration.xml"
+            >gp_segment_configuration</xref></codeph> catalog table with the new segment instance
+        information. Greenplum Database uses the <codeph>address</codeph> value of the
+          <codeph>gp_segment_configuration</codeph> catalog table when looking up host systems for
+        Greenplum interconnect (internal) communication between the master and segment instances and
+        between segment instances, and for other internal communication.</p>
+    </section>
+    <section id="multi_nic">
+      <title>Using Host Systems with Multiple NICs</title>
+      <p>If host systems are configured with multiple NICs, you can expand a Greenplum Database
+        system to use each NIC as a Greenplum host system. You must ensure that the host systems are
+        configured with sufficient resources to support all the segment instances being added to the
+        host. Also, if you enable segment mirroring, you must ensure that the expanded Greenplum
+        system configuration supports failover if a host system fails. For information about
+        Greenplum Database mirroring schemes, see <xref
+          href="../../best_practices/ha.xml#topic_ngz_qf4_tt"/>.</p>
+      <p>For example, this is a <codeph>gpexpand</codeph> configuration file for a simple Greenplum
+        system. The segment host <codeph>gp6s1</codeph> and <codeph>gp6s2</codeph> are configured
+        with two NICs, <codeph>-s1</codeph> and <codeph>-s2</codeph>, where the Greenplum Database
+        system uses each NIC as a host system. </p>
+      <codeblock>gp6s1-s2|gp6s1-s2|40001|/data/data1/gpseg2|6|2|p
+gp6s2-s1|gp6s2-s1|50000|/data/mirror1/gpseg2|9|2|m
+gp6s2-s1|gp6s2-s1|40000|/data/data1/gpseg3|7|3|p
+gp6s1-s2|gp6s1-s2|50001|/data/mirror1/gpseg3|8|3|m</codeblock>
+    </section>
     <section id="section6">
       <title>Examples</title>
       <p>Run <codeph>gpexpand</codeph> with an input file to initialize new segments and create the

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

@@ -222,7 +222,7 @@
                             <codeph>QD_PRIMARY_ARRAY</codeph>, <codeph>PRIMARY_ARRAY</codeph>, and
                             <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
+                        option. See <xref href="#topic1/section6" format="dita">Examples</xref> for
                         more information. </pd>
                 </plentry>
                 <plentry>
@@ -448,7 +448,7 @@ MIRROR_PORT_BASE = 7000</codeblock>
 /data2/mirror)</codeblock>
                     </pd>
                 </plentry>
-                <plentry>
+                <plentry id="array_params">
                     <pt>QD_PRIMARY_ARRAY, PRIMARY_ARRAY, MIRROR_ARRAY</pt>
                     <pd><b>Required</b> when using <codeph>input_configuration file</codeph> with
                             <codeph>-I</codeph> option. These parameters specify the Greenplum
@@ -467,24 +467,31 @@ MIRROR_PORT_BASE = 7000</codeblock>
                         <codeblock><varname>host</varname>~<varname>port</varname>~<varname>data_directory</varname>/<varname>seg_prefix&lt;segment_id></varname>~<varname>dbid</varname>~<varname>content_id</varname></codeblock></pd>
                     <pd>The first format populates the <codeph>hostname</codeph> and
                             <codeph>address</codeph> fields in the
-                            <codeph>gp_segment_configuration</codeph> catalog with the
-                            <i>hostname</i> and <i>address</i> values provided in the input
-                        configuration file. The second format populates <codeph>hostname</codeph>
-                        and <codeph>address</codeph> with the same value, derived from
-                        <i>host</i>.</pd>
+                            <codeph>gp_segment_configuration</codeph> catalog table with the
+                            <varname>hostname</varname> and <varname>address</varname> values
+                        provided in the input configuration file. The second format populates
+                            <codeph>hostname</codeph> and <codeph>address</codeph> fields with the
+                        same value, derived from <varname>host</varname>.</pd>
                     <pd>The Greenplum Database master always uses the value -1 for the segment ID
-                        and content ID. For
-                        example:<codeblock>QD_PRIMARY_ARRAY=127.0.0.1~5432~/gpmaster/gpsne-1~1~-1~0 
+                        and content ID. For example, <varname>seg_prefix&lt;segment_id></varname>
+                        and <varname>dbid</varname> values for <codeph>QD_PRIMARY_ARRAY</codeph> use
+                            <codeph>-1</codeph> to indicate the master
+                        instance:<codeblock>QD_PRIMARY_ARRAY=mdw~mdw~5432~/gpdata/master/gpseg<b>-1</b>~1~<b>-1</b>
 declare -a PRIMARY_ARRAY=(
-localhost~127.0.0.1~40000~/gpdata1/gpsne0~2~0~6000
-localhost~127.0.0.1~40001~/gpdata2/gpsne1~3~1~6001 
-) 
+sdw1~sdw1~40000~/gpdata/data1/gpseg0~2~0
+sdw1~sdw1~40001~/gpdata/data2/gpseg1~3~1
+sdw2~sdw2~40000~/gpdata/data1/gpseg2~4~2
+sdw2~sdw2~40001~/gpdata/data2/gpseg3~5~3
+)
 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 
+sdw2~sdw2~50000~/gpdata/mirror1/gpseg0~6~0
+sdw2~sdw2~50001~/gpdata/mirror2/gpseg1~7~1
+sdw1~sdw1~50000~/gpdata/mirror1/gpseg2~8~2
+sdw1~sdw1~50001~/gpdata/mirror2/gpseg3~9~3
 )</codeblock></pd>
-                    <pd>For recovery purposes, you can edit the segment and content IDs to match the
-                        values of an existing Greenplum Database backup.</pd>
+                    <pd>To re-create a cluster using a known Greenplum Database system
+                        configuration, you can edit the segment and content IDs to match the values
+                        of the system.</pd>
                 </plentry>
                 <plentry>
                     <pt>HEAP_CHECKSUM</pt>
@@ -501,7 +508,7 @@ localhost~127.0.0.1~50001~/gpmirror2/gpsne1~5~1~51001
                         parameter with the <codeph>gpconfig</codeph> management
                         utility:<codeblock>$ gpconfig -s data_checksums</codeblock></pd>
                 </plentry>
-                <plentry>
+                <plentry id="hba_hostnames">
                     <pt>HBA_HOSTNAMES</pt>
                     <pd><b>Optional.</b> This parameter controls whether
                             <codeph>gpinitsystem</codeph> uses IP addresses or host names in the
@@ -517,6 +524,40 @@ localhost~127.0.0.1~50001~/gpmirror2/gpsne1~5~1~51001
                 </plentry>
             </parml>
         </section>
+        <section>
+            <title>Specifying Hosts using Hostnames or IP Addresses</title>
+            <p>When initializing a Greenplum Database system with <codeph>gpinitsystem</codeph>, you
+                can specify segment hosts using either hostnames or IP addresses. For example, you
+                can use hostnames or IP addresses in the file specified with the <codeph>-h</codeph>
+                    option.<ul id="ul_ijf_tvq_bmb">
+                    <li>If you specify a hostname, the resolution of the hostname to an IP address
+                        should be done locally for security. For example, you should use entries in
+                        a local <codeph>/etc/hosts</codeph> file to map a hostname to an IP address.
+                        The resolution of a hostname to an IP address should not be performed by an
+                        external service such as a public DNS server. You must stop the Greenplum
+                        system before you change the mapping of a hostname to a different IP
+                        address.</li>
+                    <li>If you specify an IP address, the address should not be changed after the
+                        initial configuration. When segment mirroring is enabled, replication from
+                        the primary to the mirror segment will fail if the IP address changes from
+                        the configured value. For this reason, you should use a hostname when
+                        initializing a Greenplum Database system unless you have a specific
+                        requirement to use IP addresses.</li>
+                </ul></p>
+            <p>When initializing the Greenplum Database system, <codeph>gpinitsystem</codeph> uses
+                the initialization information to populate the <codeph><xref
+                        href="../../ref_guide/system_catalogs/gp_segment_configuration.xml"
+                        >gp_segment_configuration</xref></codeph> catalog table and adds hosts to
+                the <codeph>pg_hba.conf</codeph> file. By default, the host IP address is added to
+                the file. Specify the <codeph>gpinitsystem</codeph> configuration file parameter
+                        <codeph><xref href="#topic1/hba_hostnames" format="dita"
+                        >HBA_HOSTNAMES</xref>=1</codeph> to add hostnames to the file.</p>
+            <p>Greenplum Database uses the <codeph>address</codeph> value of the
+                    <codeph>gp_segment_configuration</codeph> catalog table when looking up host
+                systems for Greenplum interconnect (internal) communication between the master and
+                segment instances and between segment instances, and for other internal
+                communication.</p>
+        </section>
         <section id="section6">
             <title>Examples</title>
             <p>Initialize a Greenplum Database system by supplying a cluster configuration file and
@@ -551,11 +592,37 @@ mwd~mwd.local~7001~/data/mirror1/gpseg0~3~0
                 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>
+            <p>The following example uses a host system configured with mulitple NICs. If host
+                systems are configured with multiple NICs, you can initialize a Greenplum Database
+                system to use each NIC as a Greenplum host system. You must ensure that the host
+                systems are configured with sufficient resources to support all the segment
+                instances being added to the host. Also, if high availability is enabled, you must
+                ensure that the Greenplum system configuration supports failover if a host system
+                fails. For information about Greenplum Database mirroring schemes, see <xref
+                    href="../../best_practices/ha.xml#topic_ngz_qf4_tt"/>.</p>
+            <p>For this simple master and segment instance configuration, the host system
+                    <codeph>gp6m</codeph> is configured with two NICs <codeph>gp6m-1</codeph> and
+                    <codeph>gp6m-2</codeph>. In the configuration, the <codeph><xref
+                        href="#topic1/array_params" format="dita">QD_PRIMARY_ARRAY</xref></codeph>
+                parameter defines the master segment using <codeph>gp6m-1</codeph>. The
+                        <codeph><xref href="#topic1/array_params" format="dita"
+                    >PRIMARY_ARRAY</xref></codeph> and <codeph><xref href="#topic1/array_params"
+                        format="dita">MIRROR_ARRAY</xref></codeph> parameters use
+                    <codeph>gp6m-2</codeph> to define a primary and mirror segment instance.
+                <codeblock>QD_PRIMARY_ARRAY=gp6m~<b>gp6m-1</b>~5432~/data/master/gpseg-1~1~-1
+declare -a PRIMARY_ARRAY=(
+gp6m~<b>gp6m-2</b>~40000~/data/data1/gpseg0~2~0
+gp6s~gp6s~40000~/data/data1/gpseg1~3~1
+)
+declare -a MIRROR_ARRAY=(
+gp6s~gp6s~50000~/data/mirror1/gpseg0~4~0
+gp6m~<b>gp6m-2</b>~50000~/data/mirror1/gpseg1~5~1
+)</codeblock></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" type="topic" scope="peer">Initializing Greenplum
-                Database</xref>.</section>
+                href="../../install_guide/init_gpdb.xml" type="topic" scope="peer">Initializing
+                Greenplum Database</xref>.</section>
     </body>
 </topic>