Older Pangolin installs: Make sure UDP 21820 and Gerbil is updated for clients to work

[oschwartz10612]

Just wanted to put this builtin out there for people who may find it.

If you are struggling with getting an error like Client last hole punch is too old or the clients apps are stuck registering on the new 1.14 or 1.15 or 1.16 versions of Pangolin this could be for you.

For the clients feature to work you need to have updated Gerbil to 1.3.0 and have UDP port 21820 open on the VPS firewall and in the docker compose file.

Older installs that predated the 21820 port being configured by default will need to make this change.

Also, you will experience issues with relaying if gerbil can not resolve the real public ip of the client. If gerbil is behind a load balancer or docker is for some reason giving gerbil a private docker address, you will experience failures relaying.

Make sure to docker compose up -d with these changes or restart the whole stack.

[svandive]

With the updated Client on iOS, I have confirmed that my current setup is fully working, and I'm able to connect and have internal DNS resolution. With a Unifi UCG-Fiber Router, I did need to disable the P2P blocking in CyberSecure as recommended on the Tailscale website (pointer in Pangolin Documentation). My service is now working without the need for the relay. Thank you very much for the support.

[ercoppa]

@oschwartz10612 I cannot use port 21820, any way to make pangolin work on a custom UDP port?

[oschwartz10612]

This should work in the latest versions.

[oschwartz10612]

You could change the clients start port in the config file: https://docs.pangolin.net/self-host/advanced/config-file#param-clients-start-port

[ercoppa]

@oschwartz10612 I had to make this change otherwise it does not work for me: ercoppa@eecb4ab

Is it the right fix? If yes, I can a make a PR

[TiltedTeapot]

@ercoppa Please make a PR for this fix. It is aggravating that the https://docs.pangolin.net/self-host/advanced/config-file#param-clients-start-port config is an option but it doesn't actually work.

[ipnetxyz]

I cannot use the port 21820/udp and 51820/udp.

I've changed the docker-compose.yml

 gerbil:
 ...
    ports:
      - 51888:51888/udp
      - ...
      - 21888:21888/udp
...

the config/config.yml

gerbil:
  start_port: 51888

Restarted the stack and it shows listening on those ports:

netstat -ua | grep -E "51888|21888"
udp        0      0 0.0.0.0:21888           0.0.0.0:*
udp        0      0 0.0.0.0:51888           0.0.0.0:*

Docker logs:

pangolin | 2026-10-06T19:47:07+00:00 [warn]: [handleOlmRegisterMessage] Client last hole punch is too old and we have sites to send; skipping this register. The client is failing to hole punch and identify its network address with the server. Can the client reach the server on UDP port 21820? {"orgId":"xxx","clientId":3}

Pangolin cli:

Connection error: Unable to coordinate client P2P connection. Please ensure your client can reach the server on UDP port 21820 and try registering again.

INFO: 2026/10/06 12:47:00 Starting hole punch for 1 exit nodes
INFO: 2026/10/06 12:47:01 Websocket Connected
ERROR: 2026/10/06 12:47:35 Olm error (code: HOLEPUNCH_MISSING): Unable to coordinate client P2P connection. Please ensure your client can reach the server on UDP port 21820 and try registering again.

All clients are on v0.18.1.

Any advice on what I'm doing wrong? Is there a way to force the clients to use custom ports?

Thank you!

[TiltedTeapot]

It looks like the start_port/listenport is only set when the Gerbil exit node is first created in the Database. Maybe a database reset or edit is required to make this change retroactively.

pangolin/server/routers/gerbil/createExitNode.ts

Lines 15 to 18 in a235635

	if (!exitNodeQuery) {
	const { value: address, release } = await getNextAvailableSubnet();
	try {
	const listenPort = config.getRawConfig().gerbil.start_port;

[TiltedTeapot]

My apologies this is because the client_start_port from the config is not passed to Gerbil at all. It would need to be passed as the relayport to gerbil

[TiltedTeapot]

I've posted a draft PR #3870 to potentially fix the issue of Gerbil not knowing about the changed relay port. It is a large change and wanted to see if this aligns with the project before debugging it.

[ipnetxyz]

Thanks a lot for taking the time and effort to reply and address my challenge! Let's see where it leads :)

[TiltedTeapot]

This has been resolved in release 1.25.1

[oschwartz10612]

Thanks