TLS
Where to terminate
Section titled “Where to terminate”| Where the proxy is | What to do |
|---|---|
| On the same machine | --http-addr=/run/gitlab-mcp/server.sock. No network hop to encrypt, no certificate to rotate |
| On another machine | --tls-cert and --tls-key on the listener, with the proxy verifying it |
| Terminating for clients | The proxy’s own certificate, plus one of the two rows above for the hop behind it |
The unix socket removes the hop rather than encrypting it, and under Docker that hop is not “just loopback”: the path runs through docker-proxy and a bridge network. How the authentication budgets tell its callers apart is at the end of this page.
The listener’s own TLS
Section titled “The listener’s own TLS”gitlab-mcp-server --http --http-addr=:8443 \ --gitlab-url=https://gitlab.example.com \ --tls-cert=/etc/ssl/mcp.crt --tls-key=/etc/ssl/mcp.keyBoth flags or neither: a certificate without its key is a deployment that believes it is encrypting and is not, and startup refuses it. TLS 1.2 is the floor and no maximum is set, so a current client negotiates TLS 1.3 and 1.2 is reached only by a client that cannot go higher. Anything below 1.2 is refused. Both properties are pinned by tests that drive the real binary.
Certificate rotation without downtime
Section titled “Certificate rotation without downtime”Write the new pair over the old paths. There is nothing else to do. The certificate is served through a callback that checks the two files on each handshake and re-reads them when either has changed, so the next handshake presents the new certificate. Connections already open keep the old one until they are replaced, which is correct and is how every rotation works.
Concretely, with certbot or any renewal tool that writes the same paths:
# The renewal hook needs no signal and no restart.certbot renew --deploy-hook "true"Three properties of that path, each covered by a test:
- A half-written rotation keeps serving. Writing a certificate and its key is two writes, and between them the pair on disk does not match. The previously loaded certificate stays in service until the pair is whole again, and the failure is logged once rather than once per handshake.
- Unreadable files keep serving. A renewal that unlinks before it writes, or a mount briefly absent, does not take the listener down.
- Nothing is re-read while nothing changed. The staleness check is two
statcalls; the parse happens only when the size or modification time moved.
There is no reload signal and none is needed. SIGHUP is not handled and, under
its default disposition, terminates the process; do not send it.
The first load is still strict: at startup a path that does not exist or a key that does not match its certificate is a named startup error, because that is the one moment there is nothing to fall back to and an operator is watching.
Client certificates
Section titled “Client certificates”The listener does not do mTLS. It requests no client certificate and verifies none; authentication on it is the bearer credential, in either supported mode. Mutual TLS at the edge is therefore a property of the proxy in front, which is where it belongs for a deployment with many clients anyway, since the proxy is what holds the client CA and the revocation list:
server { listen 443 ssl; server_name mcp.example.com;
ssl_client_certificate /etc/ssl/clients-ca.pem; ssl_verify_client on; ssl_verify_depth 2;
location / { proxy_pass http://gitlab_mcp; proxy_http_version 1.1; proxy_set_header Connection ""; # Pass the verified identity on for logging, never for authorization: # the server authorizes on the GitLab credential. proxy_set_header X-Client-DN $ssl_client_s_dn; }}For the proxy-to-server hop, proxy_ssl_verify on with
proxy_ssl_trusted_certificate pointed at your private CA is the pairing for
--tls-cert on the listener.
The unix socket and the authentication budgets
Section titled “The unix socket and the authentication budgets”A unix socket has no peer address, so the authentication failure budgets, which
are keyed on the caller’s address, have nothing to tell its callers apart by.
Every connection to the socket is the one key unix.
Name the proxy on the socket as a trusted proxy and it tells the server who each caller is, exactly as a proxy on loopback TCP does:
gitlab-mcp-server --http --http-addr=/run/gitlab-mcp/server.sock \ --gitlab-url=https://gitlab.example.com \ --trusted-proxy-header=X-Real-IP --trusted-proxies=unixunix trusts the peer of a connection on the socket and no address. The header
is read by the same rule as from a TCP proxy (the first hop from the right that
is not itself a listed proxy), so a chain of proxies lists the outer ones by
address beside unix. Each caller then has budgets of its own, an IPv6 caller by
the /64 it lies in
(Authentication budgets).
Without the two flags every caller on the socket shares one budget: ten
failed authentications a minute from anywhere behind the proxy spend it for
everybody for a minute. A caller whose credential this deployment is already
serving is still served while it is spent, so the damage is bounded to
credentials the server does not currently hold: every one of them is answered
429 inside that window, a caller authenticating for the first time and one
whose entry the pool has reclaimed alike
(why the exemption is safe).
That is fine where the caller population is small or entirely trusted.
Two pairings are refused at startup, because each trusts nobody while reading as if it trusted someone:
| Pairing | Why it is refused |
|---|---|
A socket --http-addr whose --trusted-proxies lists addresses and no unix | No socket peer matches an address, so the header would never be believed and every caller would share one budget in silence |
unix in --trusted-proxies on a TCP --http-addr | No connection to a TCP listener comes from a socket peer, so the entry would trust nobody |
An earlier release started with the first pairing and ignored the header. If a
deployment that worked before now refuses to start with
--trusted-proxies does not name unix, add unix to the list.
Frequently asked questions
Can I rotate the TLS certificate without restarting?
Yes. Write the new pair over the same paths and the next handshake presents it; connections already open keep the old certificate until they are replaced. The certificate is served through a callback that stats both files on each handshake and re-reads them when either changed. A half-written pair, or files briefly unreadable, keeps the previous certificate in service and logs the reason once. No signal is needed, and SIGHUP is not a reload: it is unhandled and terminates the process.
Does the listener do mTLS?
No. It requests no client certificate and verifies none; authentication on it is the bearer credential, in either supported mode. Mutual TLS at the edge is a property of the proxy in front, which is where it belongs for a deployment with many clients anyway, since the proxy is what holds the client CA and the revocation list.
Is a unix socket the right choice for a same-machine proxy?
It removes the network hop rather than encrypting it, which is usually what you want. A unix socket has no peer address, so pass --trusted-proxy-header with --trusted-proxies=unix: the server then believes the address the proxy forwards from the socket, and each caller keeps an authentication failure budget of its own. Without them every caller on the socket shares one budget, and ten failed authentications a minute from anywhere spend it for everybody. A socket listener whose --trusted-proxies lists addresses but not unix refuses to start, since no socket peer matches an address.