Implement server-side support for the PROXY protocol

Add support for HAProxy's PROXY protocol, versions 1 and 2, so the real
client address can be recovered from connections arriving through a trusted
proxy. The new proxy_networks GUC lists the networks whose peers are allowed
to prepend a PROXY header to declare the originating client.  This list
supports unix sockets with the "unix" token.  It is empty by default, which
disables the feature.

The header is parsed lazily.  The server only looks for it on connections
coming from a trusted network and falls through to the normal startup path
otherwise.  Existing clients that are not from the proxy networks and that
do not speak the PROXY protocol are unaffected.

For connections from a trusted proxy, client_addr and client_port in
pg_stat_activity and the host-based authentication checks reflect the
address from the header, while the proxy's own endpoint is exposed via the
new proxy_addr, proxy_hostname and proxy_port columns.  The %H and %R
escapes expose the proxy information in log_line_prefix.  The proxy host and
port are also emitted in the CSV and JSON log formats.

Author: jouir

doc/src/sgml/client-auth.sgml

@@ -421,6 +421,16 @@ include_dir         <replaceable>directory</replaceable>
        These fields do not apply to <literal>local</literal> records.
       </para>
 
+      <note>
+       <para>
+        When a connection arrives through a connection-forwarding proxy and a
+        PROXY protocol header is accepted, the address matched against this
+        field is the client address declared in that header, not the proxy's
+        own address.  See <xref linkend="guc-proxy-networks"/> for
+        details.
+       </para>
+      </note>
+
       <note>
        <para>
         Users sometimes wonder why host names are handled
@@ -1708,6 +1718,17 @@ omicron         bryanh                  guest1
     since <productname>PostgreSQL</productname> does not have any way to decrypt the
     returned string to determine the actual user name.
    </para>
+
+   <para>
+    Ident authentication is rejected for connections received through
+    the <link linkend="protocol-flow-proxy">PROXY protocol</link>. A client
+    connected to the proxy rather than to the server. The port pair
+    <replaceable>X</replaceable> and <replaceable>Y</replaceable> known to the
+    server does not describe any connection that the client's ident server has
+    a record of, and the query would reach the ident server from the server's
+    address rather than the proxy's. Any answer would therefore be
+    meaningless.
+   </para>
   </sect1>
 
   <sect1 id="auth-peer">

doc/src/sgml/config.sgml

@@ -712,6 +712,51 @@ include_dir 'conf.d'
       </listitem>
      </varlistentry>
 
+     <varlistentry id="guc-proxy-networks" xreflabel="proxy_networks">
+      <term><varname>proxy_networks</varname> (<type>string</type>)
+      <indexterm>
+       <primary><varname>proxy_networks</varname> configuration parameter</primary>
+      </indexterm>
+      <indexterm>
+       <primary>PROXY protocol</primary>
+      </indexterm>
+      </term>
+      <listitem>
+       <para>
+        Specifies the networks from which the server will accept a
+        PROXY protocol header.  When the server is reached through a
+        connection-forwarding proxy (like <productname>HAProxy</productname>),
+        the proxy can prepend a small header, as defined by the
+        <ulink url="https://www.haproxy.org/download/2.9/doc/proxy-protocol.txt">PROXY
+        protocol</ulink>, that declares the address of the real client.
+        When such a header is accepted, the declared client
+        address replaces the proxy's address for host-based authentication
+        (see <xref linkend="auth-pg-hba-conf"/>) and in the server log.
+       </para>
+       <para>
+        The value is a comma-separated list of CIDR networks or the special
+        token <literal>unix</literal> for Unix-domain socket (for example
+        <literal>10.0.0.0/8, 192.168.1.10, ::1/128, unix</literal>).  A
+        PROXY protocol header is honored only when the actual peer address
+        falls within one of these networks.  A header received from any
+        other address is rejected as an invalid connection attempt, so that
+        ordinary clients cannot spoof their address.  The default is an
+        empty string, which disables the PROXY protocol support entirely.
+        This parameter can only be set in the
+        <filename>postgresql.conf</filename> file or on the server command
+        line.
+       </para>
+       <para>
+        Because a peer within these networks is treated as a proxy rather than
+        a direct client, it is <emphasis>required</emphasis> to lead with a
+        PROXY protocol header.  A connection from one of these networks that
+        begins with an ordinary startup packet, or an SSL or GSS negotiation
+        request, instead of a PROXY header is rejected. This prevents the
+        proxy's own address from being mistaken for a client's.
+       </para>
+      </listitem>
+     </varlistentry>
+
      <varlistentry id="guc-max-connections" xreflabel="max_connections">
       <term><varname>max_connections</varname> (<type>integer</type>)
       <indexterm>
@@ -8131,11 +8176,12 @@ local0.*    /var/log/postgresql
       <listitem>
        <para>
         By default, connection log messages only show the IP address of the
-        connecting host. Turning this parameter on causes logging of the
-        host name as well.  Note that depending on your host name resolution
-        setup this might impose a non-negligible performance penalty.
-        This parameter can only be set in the <filename>postgresql.conf</filename>
-        file or on the server command line.
+        connecting host and the proxy host if the connection came from a
+        trusted proxy.  Turning this parameter on causes logging of the host
+        names as well.  Note that depending on your host name resolution setup
+        this might impose a non-negligible performance penalty.  This parameter
+        can only be set in the <filename>postgresql.conf</filename> file or on
+        the server command line.
        </para>
       </listitem>
      </varlistentry>
@@ -8205,6 +8251,16 @@ local0.*    /var/log/postgresql
              <entry>Remote host name or IP address</entry>
              <entry>yes</entry>
             </row>
+            <row>
+             <entry><literal>%H</literal></entry>
+             <entry>Proxy host name or IP address</entry>
+             <entry>yes</entry>
+            </row>
+            <row>
+             <entry><literal>%R</literal></entry>
+             <entry>Proxy host name or IP address, and proxy port</entry>
+             <entry>yes</entry>
+            </row>
             <row>
              <entry><literal>%L</literal></entry>
              <entry>Local address (the IP address on the server that the
@@ -8693,6 +8749,7 @@ CREATE TABLE postgres_log
   backend_type text,
   leader_pid integer,
   query_id bigint,
+  proxy_connection text,
   PRIMARY KEY (session_id, session_line_num)
 );
 </programlisting>
@@ -8819,6 +8876,16 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv;
          <entry>number</entry>
          <entry>Client port</entry>
         </row>
+        <row>
+         <entry><literal>proxy_host</literal></entry>
+         <entry>string</entry>
+         <entry>Proxy host</entry>
+        </row>
+        <row>
+         <entry><literal>proxy_port</literal></entry>
+         <entry>number</entry>
+         <entry>Proxy port</entry>
+        </row>
         <row>
          <entry><literal>session_id</literal></entry>
          <entry>string</entry>

doc/src/sgml/monitoring.sgml

@@ -863,6 +863,10 @@ postgres   27093  0.0  0.0  30096  2752 ?        Ss   11:34   0:00 postgres: ser
        If this field is null, it indicates either that the client is
        connected via a Unix socket on the server machine or that this is an
        internal process such as autovacuum.
+       When the connection was made through a trusted proxy using the PROXY
+       protocol, this is the client address sent by the proxy, not the address
+       of the proxy itself (which is shown in <structfield>proxy_addr</structfield>
+       instead).
       </para></entry>
      </row>
 
@@ -885,6 +889,46 @@ postgres   27093  0.0  0.0  30096  2752 ?        Ss   11:34   0:00 postgres: ser
        TCP port number that the client is using for communication
        with this backend, or <literal>-1</literal> if a Unix socket is used.
        If this field is null, it indicates that this is an internal server process.
+       When the connection was made through a trusted proxy using the PROXY
+       protocol, this is the client port sent by the proxy, not the port of the
+       proxy itself (which is shown in <structfield>proxy_port</structfield>
+       instead).
+      </para></entry>
+     </row>
+
+     <row>
+      <entry role="catalog_table_entry"><para role="column_definition">
+       <structfield>proxy_addr</structfield> <type>inet</type>
+      </para>
+      <para>
+       IP address of the trusted proxy that forwarded this connection.
+       If this field is null, it indicates either that the PROXY protocol has
+       not been used, or the proxy forwarded the connection over a Unix socket,
+       or the proxy used a <literal>LOCAL</literal> command.
+      </para></entry>
+     </row>
+
+     <row>
+      <entry role="catalog_table_entry"><para role="column_definition">
+       <structfield>proxy_hostname</structfield> <type>text</type>
+      </para>
+      <para>
+       Host name of the proxy that forwarded this connection, as reported by a
+       reverse DNS lookup of <structfield>proxy_addr</structfield>. This field
+       will only be non-null when the client connected through a trusted proxy
+       using the PROXY protocol, and only when <xref linkend="guc-log-hostname"/>
+       is enabled.
+      </para></entry>
+     </row>
+
+     <row>
+      <entry role="catalog_table_entry"><para role="column_definition">
+       <structfield>proxy_port</structfield> <type>integer</type>
+      </para>
+      <para>
+       TCP port number of the trusted proxy that forwarded this connection, or
+       <literal>-1</literal> if the proxy forwarded it over a Unix socket.
+       This field is null when the PROXY protocol was not used.
       </para></entry>
      </row>
 

doc/src/sgml/protocol.sgml

@@ -1693,6 +1693,22 @@ SELCT 1/0;<!-- this typo is intentional -->
    </para>
   </sect2>
 
+  <sect2 id="protocol-flow-proxy">
+   <title><acronym>PROXY</acronym> Protocol</title>
+
+   <para>
+    When a connection is forwarded by a proxy, the address the server sees is
+    the proxy's, not the real client's.  To preserve the
+    originating address, the proxy can prepend a header conforming to the
+    <ulink url="https://www.haproxy.org/download/2.9/doc/proxy-protocol.txt">PROXY
+    protocol</ulink> designed by <productname>HAProxy</productname>.  The
+    header carries the original source and destination addresses and ports.
+    The header is sent once, before any other data, ahead of the SSLRequest,
+    GSSENCRequest, or StartupMessage.  Both version 1 (text) and version 2
+    (binary) of the protocol are accepted.
+   </para>
+  </sect2>
+
   <sect2 id="protocol-flow-ssl">
    <title><acronym>SSL</acronym> Session Encryption</title>
 

src/backend/catalog/system_views.sql

@@ -948,6 +948,9 @@ CREATE VIEW pg_stat_activity AS
             S.client_addr,
             S.client_hostname,
             S.client_port,
+            S.proxy_addr,
+            S.proxy_hostname,
+            S.proxy_port,
             S.backend_start,
             S.xact_start,
             S.query_start,

src/backend/libpq/Makefile

@@ -28,7 +28,8 @@ OBJS = \
 	pqcomm.o \
 	pqformat.o \
 	pqmq.o \
-	pqsignal.o
+	pqsignal.o \
+	proxy_protocol.o
 
 ifeq ($(with_ssl),openssl)
 OBJS += be-secure-openssl.o

src/backend/libpq/auth.c

@@ -1734,6 +1734,18 @@ ident_inet(Port *port)
 			   *la = NULL,
 				hints;
 
+	/*
+	 * Ident is incompatible with the PROXY protocol.  A proxied client
+	 * connected to the proxy, not to the server, so its ident server has no
+	 * record of any connection matching the address pair in the query.
+	 */
+	if (port->proxy_protocol)
+	{
+		ereport(LOG,
+				(errmsg("ident authentication is not supported over connections using the PROXY protocol")));
+		return STATUS_ERROR;
+	}
+
 	/*
 	 * Might look a little weird to first convert it to text and then back to
 	 * sockaddr, but it's protocol independent.

src/backend/libpq/meson.build

@@ -15,6 +15,7 @@ backend_sources += files(
   'pqformat.c',
   'pqmq.c',
   'pqsignal.c',
+  'proxy_protocol.c',
 )
 
 if ssl.found()

src/backend/libpq/pqcomm.c

@@ -1094,7 +1094,7 @@ pq_getbytes(void *b, size_t len)
  *		returns 0 if OK, EOF if trouble
  * --------------------------------
  */
-static int
+int
 pq_discardbytes(size_t len)
 {
 	size_t		amount;