CDIST-TYPE__HAPROXY_DUALSTACK(7)

📦
version 7.0.0 · 7 versions
, in fedora 43, fedora 44

💖 cdist-type__haproxy_dualstack 💖

okay bestie, so this is a manual page, it's cdist-type__haproxy_dualstack, and it's literally the glow-up your IPv6-only services have been waiting for. let's get into it 🦋

✨ NAME ✨

cdist-type__haproxy_dualstack — proxy services from a dual-stack server. that's the whole vibe. 👑

🌸 DESCRIPTION 🌸

okay so this type is a singleton (meaning there's only one of it, it's giving main character energy, no duplicates allowed 💅), and what it does is install and configure haproxy to act as a dual-stack proxy for single-stack services.

why would you want that? because it's iconic, that's why. but also: it's useful for adding IPv4 support to IPv6-only services while only using one IPv4 for like, a whole bunch of those services. one address, many services, we love efficiency fr fr ✨

by default this type uses the plain TCP proxy mode, which means:

  • there is no need for TLS termination on this host when SNI is supported 🎀
  • proxied services will not receive the client's IP address 😭 instead they'll see the proxy's IP address (that of $__target_host). yeah. that's the tradeoff bestie.

the way to solve the client-IP thing is by using the PROXY protocol, but do take into account that, e.g. nginx cannot serve both regular HTTP(S) and PROXY protocols on the same port, so you will need to use other ports for that. no cap. 💀

as a recommendation in this type: use TCP ports 8080 and 591 respectively to serve HTTP and HTTPS using the PROXY protocol. 🔥

see the EXAMPLES for more details, they're lowkey essential.

🎀 OPTIONAL PARAMETERS 🎀

  • v4proxy — proxy incoming IPv4 connections to the equivalent IPv6 endpoint. in its simplest use, it must be a NAME with an AAAA DNS entry, which is the IP address actually providing the proxied services. the full format of this argument is:
[proxy:]NAME[[:PROTOCOL_1=PORT_1]...[:PROTOCOL_N=PORT_N]]

where starting with proxy: determines that the PROXY protocol must be used, and each :PROTOCOL=PORT (e.g. :http=8080 or :https=591) is a PORT override for the given PROTOCOL (see --protocol). if it's not present, the PROTOCOL's default port will be used. 🦋

  • v6proxy — proxy incoming IPv6 connections to the equivalent IPv4 endpoint. in its simplest use, it must be a NAME with an A DNS entry, which is the IP address actually providing the proxied services. see --v4proxy for more options and details. 💜
  • protocol — can be passed multiple times or as a space-separated list of protocols. currently supported protocols are: http, https, imaps, smtps. this defaults to: http https imaps smtps. 🌈

🌟 EXAMPLES 🌟

okay this is the part where it all comes together, pay attention bestie 👑

# Proxy the IPv6-only services so IPv4-only clients can access them
# This uses HAProxy's TCP mode for http, https, imaps and smtps
__haproxy_dualstack \
    --v4proxy ipv6.chat \
    --v4proxy matrix.ungleich.ch

# Proxy the IPv6-only HTTP(S) services so IPv4-only clients can access them
# Note this means that the backend IPv6-only server will only see
# the IPv6 address of the haproxy host managed by cdist, which can be
# troublesome if this information is relevant for analytics/security/...
# See the PROXY example below
__haproxy_dualstack \
    --protocol http --protocol https \
    --v4proxy ipv6.chat \
    --v4proxy matrix.ungleich.ch

# Use the PROXY protocol to proxy the IPv6-only HTTP(S) services enabling
# IPv4-only clients to access them while maintaining the client's IP address
__haproxy_dualstack \
    --protocol http --protocol https \
    --v4proxy proxy:ipv6.chat:http=8080:https=591 \
    --v4proxy proxy:matrix.ungleich.ch:http=8080:https=591
# Note however that the PROXY protocol is not compatible with regular
# HTTP(S) protocols, so your nginx will have to listen on different ports
# with the PROXY settings.
# Note that you will need to restrict access to the 8080 port to prevent
# Client IP spoofing.
# This can be something like:
# server {
#     # listen for regular HTTP connections
#     listen [::]:80 default_server;
#     listen 80 default_server;
#     # listen for PROXY HTTP connections
#     listen [::]:8080 proxy_protocol;
#     # Accept the Client's IP from the PROXY protocol
#     real_ip_header proxy_protocol;
# }
💀 fr fr, that last bit about restricting access to port 8080 to prevent Client IP spoofing is not a joke, do not skip it.

🫶 SEE ALSO 🫶

👑 AUTHORS 👑

ungleich <foss--@--ungleich.ch> and Evilham <cvs--@--evilham.com> — absolute icons, we stan 🌸

💅 COPYING 💅

Copyright (C) 2021 ungleich glarus ag. You can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

ungleich GmbH 2021

and that's the whole page bestie, you ate that. 💖

this was cdist version 7.0.0, dated Jul 31, 2022 — so yes it's a lil vintage but it still slays ✨ 🦋

📦 where this page comes from