a2enmod proxy
a2enmod proxy_http
a2enmod headersIn situations where you have existing web sites on your server, you may find it useful to run Jenkins (or the servlet container that Jenkins runs in) behind Apache, so that you can bind Jenkins to the part of a bigger website that you may have. This section discusses some of the approaches for doing this.
Make sure that you change the Jenkins httpListenAddress from its default of 0.0.0.0 to 127.0.0.1 or any Apache-level restrictions can be easily bypassed by accessing the Jenkins port directly.
There are several different alternatives to configure Jenkins with Apache. Choose the technique that best meets your needs:
mod_proxy works by making Apache perform "reverse proxy" — when a request arrives for certain URLs, Apache becomes a proxy and forwards that request to Jenkins, then forwards the response from Jenkins back to the client.
The following Apache modules must be installed :
a2enmod proxy
a2enmod proxy_http
a2enmod headersA typical set up for mod_proxy would look like this:
ProxyPass /jenkins http://localhost:8081/jenkins nocanon
ProxyPassReverse /jenkins http://localhost:8081/jenkins
ProxyRequests Off
AllowEncodedSlashes NoDecode
# Local reverse proxy authorization override
# Most unix distribution deny proxy by default
# See /etc/apache2/mods-enabled/proxy.conf in Ubuntu
<Proxy http://localhost:8081/jenkins*>
Order deny,allow
Allow from all
</Proxy>This assumes that you run Jenkins on port 8081.
For this set up to work, the context path of Jenkins must be the same
between your Apache and Jenkins (that is, you can’t run Jenkins on
http://localhost:8081/ci and have it exposed at
http://localhost:80/jenkins).
Set the context path in Windows by modifying the jenkins.xml
configuration file and adding --prefix=/jenkins (or similar) to the
<arguments> entry.
Set the context path when using the Linux package
by running systemctl edit jenkins and adding the following:
[Service]
Environment="JENKINS_PREFIX=/jenkins"When running on a dedicated server and you are using / as context, make sure you add a slash at the end of all URLs in proxy params in apache. Otherwise you might run into proxy errors. So
ProxyPass / http://localhost:8080/ nocanoninstead of
ProxyPass / http://localhost:8080 nocanon # wont workNote that this does not apply to the ProxyPassMatch directive,
which behaves differently than ProxyPass.
Below is an example of ProxyPassMatch to proxy all URLs other than
/.well-known (a URL required by letsencrypt):
ProxyPassMatch ^/(?\!.well-known) http://localhost:8080 nocanonThe ProxyRequests Off prevents Apache from functioning as a forward proxy server (except for ProxyPass), it is advised to include it unless the server should function as a proxy.
Both the nocanon option to ProxyPass, and
AllowEncodedSlashes NoDecode, are required for certain Jenkins
features to work.
If you are running Apache on a Security-Enhanced Linux (SE-Linux) machine it is essential to make SE-Linux do the right thing by issuing as root
setsebool -P httpd_can_network_connect trueIf this is not issued Apache will not be allowed to forward proxy requests to Jenkins and only an error message will be displayed.
Because Jenkins already compress its output, you can not use the normal proxy-html filter to modify urls:
SetOutputFilter proxy-htmlInstead you can use the following:
SetOutputFilter INFLATE;proxy-html;DEFLATE
ProxyHTMLURLMap http://your_server:8080/jenkins /jenkinsBut since Jenkins seems to be well behaved it’s even better to just not use SetOutputFilter and ProxyHTMLURLMap.
If there are problems with Jenkins sometimes servicing random garbage pages, then the following may help:
SetEnv proxy-nokeepalive 1Some plug-ins determine URLs from client requests from Host header, so
if you experience some problems with wrong URLs, you can try to switch
on ProxyPreserveHost directive, which is switched off by default:
ProxyPreserveHost OnYou can add an additional ProxyPassReverse directive
to redirect non-SSL URLs generated by Jenkins to the SSL side.
Assuming that your webserver is your.host.com, placing the following within
the SSL virtual host definition will do the trick:
ProxyRequests Off
ProxyPreserveHost On
AllowEncodedSlashes NoDecode
<Proxy http://localhost:8081/jenkins*>
Order deny,allow
Allow from all
</Proxy>
ProxyPass /jenkins http://localhost:8081/jenkins nocanon
ProxyPassReverse /jenkins http://localhost:8081/jenkins
ProxyPassReverse /jenkins http://your.host.com/jenkinsYet another option is to rewrite the Location headers that contain non-ssl URL’s generated by Jenkins. If you want to access Jenkins from https://www.example.com/jenkins, placing the following within the SSL virtual host definition also works:
ProxyRequests Off
ProxyPreserveHost On
ProxyPass /jenkins/ http://localhost:8081/jenkins/ nocanon
AllowEncodedSlashes NoDecode
<Location /jenkins/>
ProxyPassReverse /
Order deny,allow
Allow from all
</Location>
Header edit Location ^http://www.example.com/jenkins/ https://www.example.com/jenkins/But it may also work fine to just use simple forwarding as above (the first HTTPS snippet), and add
RequestHeader set X-Forwarded-Proto "https"
RequestHeader set X-Forwarded-Port "443"in the HTTPS site configuration, as the Docker demo (below) does.
(X-Forwarded-Port is not interpreted by Jenkins prior to
JENKINS-23294 so it
may also be desirable to configure the servlet container to specify the
originating port.)
NameVirtualHost *:80
NameVirtualHost *:443
<VirtualHost *:80>
ServerAdmin webmaster@localhost
Redirect permanent / https://www.example.com/
</VirtualHost>
<VirtualHost *:443>
SSLEngine on
SSLCertificateFile /etc/ssl/certs/cert.pem
ServerAdmin webmaster@localhost
ProxyRequests Off
ProxyPreserveHost On
AllowEncodedSlashes NoDecode
<Proxy *>
Order deny,allow
Allow from all
</Proxy>
ProxyPass / http://localhost:8080/ nocanon
ProxyPassReverse / http://localhost:8080/
ProxyPassReverse / http://www.example.com/
RequestHeader set X-Forwarded-Proto "https"
RequestHeader set X-Forwarded-Port "443"
</VirtualHost>The Apache mod_rewrite module can be used to configure an Apache reverse proxy for Jenkins.
The following Apache modules must be installed :
a2enmod rewrite
a2enmod proxy
a2enmod proxy_httpA typical mod_rewrite configuration would look like this:
# Use last flag because no more rewrite can be applied after proxy pass
# NE makes sure slashes are not re-encoded.
# Apache does not re-encode spaces though, we ask Apache to encode it again with the B flag
# BNP tells apache to use %20 instead of + to re-encode the space
RewriteRule ^/jenkins(.*)$ http://localhost:8081/jenkins$1 [P,L,NE,B=\ \,BNP]
ProxyPassReverse /jenkins http://localhost:8081/jenkins
ProxyRequests Off
AllowEncodedSlashes NoDecode
# Local reverse proxy authorization override
# Most unix distribution deny proxy by default
# See /etc/apache2/mods-enabled/proxy.conf in Ubuntu
<Proxy http://localhost:8081/jenkins*>
Order deny,allow
Allow from all
</Proxy>
# If using HTTPS, add the following directives
# RequestHeader set X-Forwarded-Proto "https"
# RequestHeader set X-Forwarded-Port "443"This assumes that you run Jenkins on port 8081. For this set up to work, the context path of Jenkins must be the same between your Apache and Jenkins (that is, you can’t run Jenkins on http://localhost:8081/ci and have it exposed at http://localhost:80/jenkins)
The ProxyRequests Off prevents Apache from functioning as a forward proxy server (except for ProxyPass), it is advised to include it unless the server should function as a proxy.
Using the plain CLI protocol with the HTTP(S) transport to access Jenkins through an Apache reverse proxy does not work. See JENKINS-47279 - Full-duplex HTTP(S) transport with plain CLI protocol does not work with Apache reverse proxy for more details. As a workaround, you can use the CLI over SSH.
If using Apache check that nocanon is set on ProxyPass and that AllowEncodedSlashes is set.
AllowEncodedSlashes is not inherited in Apache configs, so this directive must be placed inside the VirtualHost definition.
Please submit your feedback about this page through this quick form.
Alternatively, if you don't wish to complete the quick form, you can simply indicate if you found this page helpful?
See existing feedback here.