A reverse proxy refers to a server used to retrieve resources on behalf of a client from one or more servers.
Reverse proxies are a powerful and popular tool that includes load balancing across multiple servers, improving security by hiding the application backend, content caching, and more.
When working with Jenkins, you may use a reverse proxy to allow users to access the Jenkins dashboard using a domain or subdomain. A reverse proxy can also allow you to improve the security of the Jenkins cluster. The reverse proxy will be a go-between for a client and the Jenkins server.
An example of reverse proxies we can use with Jenkins includes Apache and Nginx, HAProxy, Microsoft IIS, Envoy, and more. Of course, you can also configure other reverse proxies with Jenkins and the choice of which one to use will depend on your specific requirements and infrastructure.
However, once you configure Jenkins with a Reverse proxy, you may encounter an error such as “ERROR! Reverse proxy misconfigured.”
This tutorial will cover basic methods you can use to diagnose and fix such an error.
What Causes this Error?
It is good to remember that there is no definite answer as to what may cause this error. The reverse proxy configuration will vary depending on the target server. However, the primary cause of this error is missing Headers in the request from the reverse proxy to Jenkins.
How to Fix this Error?
No matter which reverse proxy you use, you must ensure the following headers are included in all the requests to Jenkins.
You can do this by adding the Headers to your Reverse proxy configuration. The headers include:
- X-Forwarded-Proto.
- X-Forwarded-Host
- X-Forwarded-Port
You can use the mod_rewrite configuration in Apache and add the following options:
RequestHeader set X-Forwarded-Port "443"
For Nginx, use the configuration:
proxy_set_header X-Forwarded-Port 443;
In HAProxy:
http-request add-header X-Forwarded-Proto https
Verify the Incoming Headers
You can check the headers that are reaching Jenkins from the reverse proxy using the script shown below:
def headerNames = req.getHeaderNames();
while (headerNames.hasMoreElements()) {
def headerName = headerNames.nextElement();
if (!headerName.toLowerCase().startsWith("x-forward")) continue
println(headerName+":");
def headers = req.getHeaders(headerName);
while (headers.hasMoreElements()) {
def headerValue = headers.nextElement();
println("\t" + headerValue);
}
}
The script above should return the headers that are reaching Jenkins. An example of the expected output:
domain.com
X-Forwarded-Proto:
https
X-Forwarded-Port:
443
X-Forwarded-For:
<client_ip>
If you see the X-Forwarded-Proto and X-Forwarded-Port headers, the reverse proxy is configured correctly. However, if the issue persists, check the Jenkins servlet.
Conclusion
We discussed one of the common errors you may encounter when using Jenkins with a reverse proxy and how you can fix it.
