bug: proxy_protocol listeners fail to bind IPv6 even when enable_ipv6: true

[twellck]

Current Behavior

When running APISIX in an IPv6 environment (e.g., K8s IPv6 SingleStack) with enable_ipv6: true, the standard node_listen and SSL ports correctly bind to [::]. However, ports defined under proxy_protocol (e.g., listen_https_port) fail to create an IPv6 listener and default to IPv4 (0.0.0.0) only.

This causes connection failures for IPv6-only load balancers (like AWS NLB in IPv6 mode) trying to connect via Proxy Protocol.

Expected Behavior

When apisix.enable_ipv6 is set to true in config.yaml, all listening ports configured in APISIX (including proxy_protocol ports) should bind to both IPv4 (0.0.0.0) and IPv6 ([::]) interfaces.

For a configuration defining proxy_protocol.listen_https_port: 9443, the generated nginx.conf should contain the IPv6 listener directive alongside the IPv4 one:

# Expected output in nginx.conf
listen 9443 ssl default_server proxy_protocol;
listen [::]:9443 ssl default_server proxy_protocol;  <-- Missing

Technical Details:
The issue appears to be located in ngx_tpl.lua & apisix/cli/ops.lua.
While node_listen and ssl.listen are processed via the listen_table_insert helper function (which correctly injects the [::] entry when enable_ipv6 is true), the proxy_protocol configuration does not follow the same pre-processing steps.

Instead, the raw port number is passed to ngx_tpl.lua, generating a bare listen <port> directive, breaking connectivity in IPv6-only environments.

Error Logs

N/A

Steps to Reproduce

1. In config.yaml, set enable_ipv6: true.
2. Enable proxy_protocol and set listen_https_port: 9443 (or any valid port).
3. Generate the config/start APISIX.
4. Check the generated nginx.conf for the missing [::] listener.

Environment

• APISIX version (run apisix version): 3.14.1
• Operating system (run uname -a): 6.12.58-82.121.amzn2023.aarch64
• OpenResty / Nginx version (run openresty -V or nginx -V): 1.27.1.2
• etcd version, if relevant (run curl http://127.0.0.1:9090/v1/server_info):

---

Note: AI helped format this issue. The issue identification and proposed solutions are my own work.

[twellck]

Temporary Workaround

For anyone facing this issue, you can temporarily fix it by manually injecting the missing IPv6 listener.

If using config.yaml
Add the snippet to nginx_config:

nginx_config:
  http_server_configuration_snippet: |
    # Manually bind IPv6 for the proxy protocol port (See https://github.com/apache/apisix/issues/12828)
    listen [::]:9443 ssl default_server proxy_protocol;

If using the official apisix Helm Chart (values.yaml)
Set the snippet under nginx.configurationSnippet.httpSrv:

nginx:
  configurationSnippet:
    httpSrv: |
      # Manually bind IPv6 for the proxy protocol port (See https://github.com/apache/apisix/issues/12828)
      listen [::]:9443 ssl default_server proxy_protocol;

Notes:

• Replace 9443 with your specific configured port.
• If using listen_http_port (plaintext), remove the ssl keyword from the listen directive.

This forces Nginx to bind the IPv6 address for that port alongside the auto-generated IPv4 binding.

[Baoyuantop]

Hi @twellck, thank you for your report and the temporary solution. The missing nginx configuration can be resolved through customization: https://apisix.apache.org/docs/apisix/customize-nginx-configuration/

We can consider dynamically generating this configuration based on the proxy_protocol setting. PRs are welcome.

[twellck]

Hi @Baoyuantop, thanks for the confirmation! I understand that the configuration snippet is the interim solution for now.

I am happy to work on the PR to implement the dynamic generation this week 👍

[Baoyuantop]

Currently, if IPv6 and proxy_protocol are enabled like:

apisix:
  enable_ipv6: true
  proxy_protocol:
    listen_http_port: 9181
    listen_https_port: 9182
    enable_tcp_pp: true
    enable_tcp_pp_to_upstream: true

The final Nginx configuration generated by APISIX is:

listen 0.0.0.0:9080 default_server reuseport;
listen [::]:9080 default_server reuseport;
listen 0.0.0.0:9443 ssl default_server reuseport;
listen [::]:9443 ssl default_server reuseport;
listen 9181 default_server proxy_protocol;
listen 9182 ssl default_server proxy_protocol;

The port configured for proxy_protocol does not listen on IPv6 addresses, which is a potential bug that requires fixing. We need to dynamically generate the corresponding Nginx configuration for proxy_protocol based on the enable_ipv6 setting.

Welcome to submit a PR to modify this issue @twellck