Reverse proxy

Reverse proxy - Squid

In situations where you want a user friendly url to access Jenkins (Not port 8080), it may make sense run Jenkins behind Squid, so that you can access Jenkins on port 80 or 443. This section discusses some of the approaches for doing this.

Squid 2.6

Using Squid 2.6:

acl all src 0.0.0.0/0.0.0.0
acl localhost src 127.0.0.1/255.255.255.255
acl manager proto cache_object
acl to_localhost dst 127.0.0.0/8
acl valid_dst dstdomain .YOUR_DOMAIN ci

cache_replacement_policy heap LFUDA
memory_replacement_policy heap GDSF

cache_dir ufs /var/spool/squid 512 16 256
cache_mem 512 MB
maximum_object_size 12000 KB

## http --> https redirect
## don't forget to update "Jenkins URL" on https://ci.YOUR_DOMAIN/configure
#acl httpPort myport 80
#http_access deny httpPort
#deny_info https://ci.YOUR_DOMAIN/ httpPort

cache_peer localhost parent 8080 0 originserver name=myAccel
coredump_dir /var/spool/squid
hierarchy_stoplist cgi-bin
http_access allow localhost
http_access allow manager localhost
http_access allow valid_dst
http_access deny all
http_access deny manager

## mkdir /etc/squid/ssl/ && cd /etc/squid/ssl/
## to generate your self-signed certificate
## openssl genrsa -out jenkins.key 1024
## openssl req -new -key jenkins.key -x509 -out jenkins.crt -days 999
http_port 80 vhost
#https_port 443 cert=/etc/squid/ssl/jenkins.crt key=/etc/squid/ssl/jenkins.key vhost

http_reply_access allow all
icp_access allow all

refresh_pattern -i \.jp(e?g|gif|png|ico)   300  20%  600 override-expire

# Combine following THREE LINES into a SINGLE LINE for Squid
logformat combined %>a %ui %un \[%tl\]
          "%rm %ru HTTP/%rv" %Hs %<st
          "%{Referer}>h" "%{User-Agent}>h" %Ss:%Sh
strip_query_terms off
access_log /var/log/squid/access.log combined

visible_hostname ci.YOUR_DOMAIN

This assumes that you run Jenkins on localhost port 8080. But you can have it on an other server / different port (adjust line starting with cache_peer)

Of course replace YOUR_DOMAIN with your domain.

With ssl

Remove one level of comment

 sed s/^#// /etc/squid/squid.conf

Note: If you use the swarm client plugin, the nodes may report:

Caused by: sun.security.validator.ValidatorException:
    PKIX path building failed: sun.security.provider.certpath.SunCertPathBuilderException:
        unable to find valid certification path to requested target
        at sun.security.validator.PKIXValidator.doBuild(PKIXValidator.java:285)
        at sun.security.validator.PKIXValidator.engineValidate(PKIXValidator.java:191)
        at sun.security.validator.Validator.validate(Validator.java:218)
        at c.s.n.s.i.s.X509TrustManagerImpl.validate(X509TrustManagerImpl.java:126)
        at c.s.n.s.i.s.X509TrustManagerImpl.checkServerTrusted(X509TrustManagerImpl.java:209)
        at c.s.n.s.i.s.X509TrustManagerImpl.checkServerTrusted(X509TrustManagerImpl.java:249)
        at c.s.n.s.i.s.ClientHandshaker.serverCertificate(ClientHandshaker.java:1014)
        ... 13 more
Caused by: sun.security.provider.certpath.SunCertPathBuilderException:
        unable to find valid certification path to requested target

You may be able to avoid that message with the -noCertificateCheck argument to agent.jar. That will disable server certificate checking from the agent.

Unix domain sockets

Jenkins can listen on a Unix domain socket instead of a TCP port, which some reverse proxies use to connect to it, such as Apache and HAProxy. Squid can’t connect to Jenkins in this way. Squid forwards requests to a cache_peer, which is always addressed by a host name and an HTTP port (cache_peer hostname type http-port icp-port [options]), and Squid has no option to reach a peer through a Unix domain socket.

When Jenkins is behind Squid, keep Jenkins listening on a TCP port, as in the example above. If Squid and Jenkins run on the same host, you can still keep Jenkins off the network by listening on the loopback address only. With the Linux packages, set JENKINS_LISTEN_ADDRESS with systemctl edit jenkins:

[Service]
Environment="JENKINS_LISTEN_ADDRESS=127.0.0.1"

This passes --httpListenAddress=127.0.0.1 to Jenkins. Then point Squid at the same address instead of localhost, which may resolve to the IPv6 address ::1:

cache_peer 127.0.0.1 parent 8080 0 originserver name=myAccel

systemctl edit only saves the setting, which takes effect the next time Jenkins is restarted (see Managing systemd services). So apply the Squid change first, while Jenkins still listens on all addresses, and then restart Jenkins so that it listens on 127.0.0.1 only:

sudo squid -k reconfigure
sudo systemctl restart jenkins

Restarting Jenkins interrupts running builds. To let them finish first, use Manage Jenkins > Prepare for Shutdown before restarting.

Context path

The context path is the prefix of a URL path. The Jenkins controller and the reverse proxy must use the same context path. For example, if the Jenkins controller URL is https://www.example.com/jenkins/ then the --prefix=/jenkins argument must be included in the Jenkins controller command line arguments.

Set the context path when using the Linux packages by running systemctl edit jenkins and adding the following:

[Service]
Environment="JENKINS_PREFIX=/jenkins"

Set the context path on Windows controllers by including the --prefix command line argument in the jenkins.xml file in the installation directory.

Ensure that Jenkins is running at the context path where your reverse proxy is serving Jenkins. You will have the least pain if you keep to this principle.

The --prefix command line argument is not needed if the context path is empty. For example, the URL https://jenkins.example.com/ has an empty context path.

User Handbook

Tutorials

Resources

Reverse proxy - Squid

Squid 2.6

With ssl

Unix domain sockets

Context path