MariaDB starting with 10.3.1

Support for the proxy protocol was added in MariaDB 10.3.1.

The proxy protocol allows proxy programs to relay the IP of the clients to the server programs. It is important in case of MariaDB, since IP information is actually a part of user identity.

How Proxy Protocol Works

As per the proxy protocol specification, the connecting client can prefix its first packet with a proxy protocol header. The server will parse the header and assume the client's IP address is the one set in the proxy header.

For example, if a client sends the proxy header (V1, text) which is "PROXY TCP4 56324 443\r\n", the server, after parsing, assumes the client's IP is

MariaDB server understands both Version 1 (text) and Version 2 (binary) of the proxy header.

Enabling Proxy Protocol in MariaDB Server

To enable use of the proxy protocol, it is necessary to specify subnetworks that are allowed to send proxy headers, using the proxy-protocol-networks server variable.

proxy-protocol-networks is a either comma-separated list of (sub)networks or IP addresses. One also can use 'localhost' in this list, which means Unix domain socket/named pipe/shared memory connections are allowed as well. Or, proxy-protocol-networks can be set to *, meaning that proxy headers are allowed from any client. * should be used with extreme care, as it might have security implications.

Example in my.ini/my.cnf

proxy-protocol-networks=::1, ,localhost

allows IPv6 connections from local machine ::1, from IP addresses starting with 192.128, and from connections made with Unix domain sockets or named pipes.

Client-Side Support for Proxy Protocol

Since the functionality is suited only to very specific proxy-like programs, most client APIs do not provide support for sending proxy headers. One exception is Connector/C version 3 or later. One can now use mysql_optionsv():

mysql_optionsv(mysql, MARIADB_OPT_PROXY_HEADER, header,  header_size)

prior to mysql_real_connect() or mysql_connect(), to send the header. In the call above _header_ is the proxy header with the type void *, and _header_size_ is its size in bytes (type is size_t).


const char *hdr="PROXY TCP4 56324 443\r\n";
mysql_optionsv(mysql, MARIADB_OPT_PROXY_HEADER, hdr,  strlen(hdr));

See Also


Comments loading...