Reverse proxy - Squid

This site is the new docs site currently being tested. For the actual docs in use please go to https://www.jenkins.io/doc.

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.

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.