In 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 Nginx, so that you can bind Jenkins to the part of a bigger website that you may have. This document 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 configure the firewall to block request on the port Jenkins is bound to, otherwise any IIS-level restrictions can be easily bypassed by hitting the Jenkins port directly.

Requirements

IIS 7.0 or greater.
- IIS 8.5 or greater if you want Certificate Rebind.
URL Rewrite 2.1 or greater.
- As the announcement explains, it introduces a feature flag to turn off the default non-compliant-RFC3986 behavior. Which is what we want.
Application Request Routing 3.0 or greater.
Server access

Example use case

I have a dedicated Jenkins installation on a Windos Server 2012 R2 server with a Common Name of VRTJENKINS01 in the Active Directory domain acme.example and is reachable by the Fully Qualified Domain Name vrtjenkins01.acme.example. Additionally Jenkins runs on port 8080 and already listens to 127.0.0.1 instead of 0.0.0.0 and the server has additional DNS names: jenkins andjenkins.acme.example.

I want to have an IIS installation which acts as a TLS/SSL terminating reverse proxy. In combination with our in-house Active Directory Certificate Services (ADCS, Microsoft's Certificate Authority software) this should make certificate management a lot easier since Windows can be configured to automatically renew certificates, and the IIS 8.5+ Certificate Rebind feature can listen to renewal events (which contain the fingerprints of both the old and new certificate) and update the relevant bind(s) to use the fresh certificate. This would ensure that after the initial manual request it would only be necessary to manually change TLS/SSL related settings when the set of Alternate Subject Names on the certificate IIS presents should change.

IIS will only have to act as 1) a reverse proxy for Jenkins 2) redirect non-canonical URLs to the canonical URL: https://jenkins.acme.example/

I have installed the IIS (8.5) role using the Add Roles and Features Wizard with the all the default and also the following non-default features:

HTTP Redirection (Under Common HTTP Features, to redirect http(s)://jenkins/, etc. to https://jenkins.acme.example/)
WebSocket Protocol (Under Application Development, because I felt like it)

Then I installed URL Rewrite and Application Request Routing.

Configuration Time

Enabling Reverse Proxy functionality

In the Internet Information Services (IIS) Manager click on the VRTJENKINS01 server.
Go to Application Request Routing Cache.
In the Actions panel click on Server Proxy Settings...
Enable the proxy
Disable the Reverse rewrite host in response header
1. Don't worry, it will work, just follow the rest of the instructions
Apply (the Actions panel again)

Configuring TLS/SSL

Out of scope, there are enough tutorials on the rest of the interwebs for this part. The rest of this tutorial will assume it has been configured with a certificate trusted by your browser of choice.

Configuring rules for response rewriting

Go to the Default Web Site
Go to URL Rewrite
In the Actions panel click View Server Variables...
Add the following is not already define on the server level:
1. Name: HTTP_FORWARDED
Click on Back to Rules
Click on Add Rule(s)...
Select Reverse Proxy and click on OK
Enter jenkins.acme.example and click on OK
Open the rule you just created
Under Conditions add:
1. Condition input: {CACHE_URL}
2. Pattern: ^(http|ws)s://
Under Server Variables add:
1. Name: HTTP_FORWARDED, Value: for={REMOTE_ADDR};by={LOCAL_ADDR};host="{HTTP_HOST}";proto="https", Replace: yes
  1. Jenkins runs under Jetty, Jetty supports RFC7239, so all should be well.
Under Action change:
1. Rewrite URL to {C:1}://jenkins.acme.example:8080{UNENCODED_URL}
  1. Note that there is no slash between the port number and the opening curly bracket
2. Remove the check from the Append query string checkbox
Apply the changes.
Edit C:\Windows\System32\drivers\etc\hosts so that jenkins.acme.example points to 127.0.0.1
1. When resolving names Windows will check if the name is its own name before consulting the hosts file. Meaning that adding vrtjenkins01 orvrtjenkins01.acme.example to the hosts file won't have any effect.
  1. The hosts file will however be consulted before consulting the DNS infrastructure

Experiencing the dreaded "It appears that your reverse proxy set up is broken." error for yourself

https://jenkins.acme.example/configure
Configure the Jenkins URL to be https://jenkins.acme.example/ and Save the change
Go to Configure Global Security and enable Enable proxy compatibility if you have already enabled Prevent Cross Site Request Forgery exploits
Go to https://jenkins.acme.example/manage
You will still experience the "It appears that your reverse proxy set up is broken." as expected
1. If you do not get that at this point, then that is very weird... Continue anyway.
Right click the Configure System link and choose to inspect the element.
1. Make sure you are still on the Manage page as you will want it as your referrer
Change the value of the href attribute to be administrativeMonitor/hudson.diagnosis.ReverseProxySetupMonitor/test
Open the link you just changed in a new tab.
1. Keep this tab open
Observe the "https://jenkins.acme.example/manage vs http:" error and bask in its glory
1. a white page served with HTTP status code is 200 indicates all is well
  1. If you do get that at this point, then that is very weird... Continue anyway.

Fixing the errors

In IIS Manager got to Application Pools then edit DefaultAppPool so that the .NET CLR versionis No Managed Code
1. You might find that this is not necessary (at far as you can tell) for your setup, since IIS will only act as a TLS/SSL offloading reverse proxy, we don't need it. IIS on Windows 7 does appear to need this to be turned off for some urls (https://jenkins.acme.example/*)
Then go to Sites → Default Web Site → Request Filtering and in the Actions panel choose Edit Feature Settings... and turn on Allow doube escaping
1. This is so IIS forwards URLs like https://jenkins.acme.example/%2525 to Jenkins instead of showing an IIS error page
Last, but not least, go to Sites → Default Web Site → Configuration Editor and change the Section to system.webServer/rewrite/rules
Now you should see the URL Rewrite 2.1 property useOriginalURLEncoding listed, if not install URL Rewrite 2.1 using the x86 or x64 installer, not the WebPI one and resume from here after a reboot.
Change useOriginalURLEncoding to False
1. As the URL Rewrite 2.1 announcement this will change the value of {UNENCODED_URL} to make it RFC3986 and usable for reverse proxy forwarding purposes
2. original as in pre 2.1 behaviour.
Refresh that tab you were supposed to keep open, or recreate it.
1. Again, take some time to bask in its glory
It should now be white, also the Manage page should no longer complain!

Continue configuring IIS

Some of the things you might want but I won't cover:

Hypertext Strict Transport Security headers
Redirecting from non canonical URLs to the canonical URL (ok, sort of covered this in the web.config example)
The X-UA-Compatibility header so that Internet Explorer 11 (or 9, or ...) won't claim to be IE 7 for intranet sites
Use IIS Crypto to configure cipher suites
...

A working web.config

web.config

<?xml version="1.0" encoding="UTF-8"?>

<configuration>

    <system.webServer>

        <rewrite>

            <rules useOriginalURLEncoding="false">

                <rule name="CanonicalHostNameRule2" stopProcessing="true">

                    <match url="(.*)" />

                    <conditions trackAllCaptures="true">

                        <add input="{CACHE_URL}" pattern="^(http|ws)://" />

                        <add input="{HTTP_HOST}" pattern="^jenkins$|^jenkins\.acme\.example$|^vrtjenkins01$|^vrtjenkins01\.acme\.example$" />

                    </conditions>

                    <action type="Redirect" url="{C:1}s://jenkins.acme.example{UNENCODED_URL}" appendQueryString="false" redirectType="Permanent" />

                </rule>

                <rule name="CanonicalHostNameRule1" stopProcessing="true">

                    <match url="(.*)" />

                    <conditions trackAllCaptures="true">

                        <add input="{CACHE_URL}" pattern="^(https|wss)://" />

                        <add input="{HTTP_HOST}" pattern="^jenkins$|^vrtjenkins01$|^vrtjenkins01\.acme\.example$" />

                    </conditions>

                    <action type="Redirect" url="{C:1}://jenkins.acme.example{UNENCODED_URL}" appendQueryString="false" redirectType="Permanent" />

                </rule>

                <rule name="ReverseProxyInboundRule1" stopProcessing="true">

                    <match url="(.*)" />

                    <action type="Rewrite" url="{C:1}://jenkins.acme.example:8080{UNENCODED_URL}" appendQueryString="false" />

                    <serverVariables>

                        <set name="HTTP_FORWARDED" value="for={REMOTE_ADDR};by={LOCAL_ADDR};host=&quot;{HTTP_HOST}&quot;;proto=&quot;https&quot;" />

                    </serverVariables>

                    <conditions trackAllCaptures="true">

                        <add input="{CACHE_URL}" pattern="^(http|ws)s://" />

                        <add input="{HTTP_HOST}" pattern="^jenkins\.acme\.example$" />

                    </conditions>

                </rule>

            </rules>

        </rewrite>

        <security>

            <requestFiltering allowDoubleEscaping="true" />

        </security>

    </system.webServer>

</configuration>

Complain about it still not working

Leave a comment or complain to me over at twitter (@Darsstar)

	permalink to the latest
	2.9.8	SHA-1: 3110f73a7f287eb026c81cfb83463c814a6b98f2, SHA-256: 823ff5f6d86a251cb9294540ccb6521269e0f6a0ad32580821cb069984e0d107
	2.9.7.1	SHA-1: 45c29bfd5e8c82f9cdf35612b5c33c1ee1e10626, SHA-256: 28dbc04f2a4798a45130d8d43f7582b44a617fbc663ecfa47c298d702b0e6730
	2.8.11.3	SHA-1: 80a68e4764f260518dcec13d8d7e6ae0ba62ee19, SHA-256: a36d07ea693c27f658c6135961342283aab9869ec4219c4badbf0c952a356ca8
	2.8.11.2	SHA-1: 41c4704f93cfa9e412862980fd8c02da46e9021f, SHA-256: 163e005e9335fb7b00afb00d3b0530b034f3612abd1639d1b17ec1e8f5a88902
	2.8.11.1	SHA-1: cd361c6caa21f4e842edb0fd9d9bdc47c0b276e9, SHA-256: 4bd83299620d64ad0b439faa438050de8f460d461808216792372f35ce085d27
	2.8.10.1	SHA-1: b1d21ada65157ea31b7d8c81b59beb7b6225a7a4, SHA-256: ea5cda3192e890500d1c09a123962cd576e2a6c8946f9f720511493b0cd7666a
	2.8.7.0	SHA-1: 52769994b1e423f0775eba482837334124ca640f, SHA-256: 337ac82bee687b00e8ee9a06d598122ebcb8e34859852d1034e5d6bb9561c274
	2.7.3	SHA-1: 5bffd74b8d1ef6cd848c81c76c1c901489ad009b, SHA-256: 6dfa1ba3db32ae47630b239399c3fc8d9102ff0b523a5c33dd32bc88d9874837
	2.7.2	SHA-1: 88f9cb2aeb23bc417019fc867becaf730c6a74ca, SHA-256: 3f9cbaffa4fec74862766b486628aeec5c34112f258b41b28123bf4eb6156abd
	2.7.1	SHA-1: b8e2f6cc3a8742e9be70afd14efabd98296a237b, SHA-256: fda8b9d6d0e730e074b8e5aa39563e45b2fdf2acb2fdba41a79ce6508d9cb181
	2.7.0	SHA-1: fc0d484dca296dc738aaccaafec4a11f529a3cf2, SHA-256: fbda324d7e2e6fe555519002d87b31dc1be257a250b887bb96c996eb84d9d8fc
	2.6.5	SHA-1: be1a5ffb2f37d0f43ea140383294520649d15903, SHA-256: df13d324d379a726c943e5bb707fd644ff5f4ba55e25bb719a056ee554810f98
	2.6.4	SHA-1: 1e0011d4de4fe3f18103d71e6f00ed00d3cad5b4, SHA-256: e2d285bc8d8dd1c7c8b1f54c76521f810fcab943fb668f504bdee924d470fe07
	2.6.3	SHA-1: 67734b5ba3d639d99da75762c2aa3f312da306bb, SHA-256: 0d21e12de375ccc4a1ba0363396dccab5dda61fbeb5076e6b479b1b4ea4f83ea
	2.6.2	SHA-1: 02b3a0300602e56af9a12605bd52c41ba73361a9, SHA-256: 6393d16d1d2d185586ed368ab32e920bc81ba3e642e18795f4b388df26eb6050
	2.6.1	SHA-1: c6cb498f755c52c44486e41b3b02f10633175e69, SHA-256: e6552acce2b4c1916a7432562a409a00faa99fb4479bca4739adaec77a22a02f
	2.6.0	SHA-1: 67cc9223d65202bc33a59f7e51faba15134e47c6, SHA-256: d9664eea7362a7654a25a79f6a403fc7f487238068303873e55930515c85e649
	2.5.5	SHA-1: 838d219be5dca3a5954b0ced4e9aa6c15a929e2a, SHA-256: c6bcff8eb45e0cbe591b372763cdfb88e01eb7fbf4a3c425d25626a4b258e963
	2.5.4	SHA-1: 20d302d9b8796f28920954ba0da0267ab34384a0, SHA-256: 2e092b7a579d4d24110a62d013009bfac2a25f5db0f63860819b588f873854e3

搜尋此網誌

小記錄

我的Jenkins安裝紀錄

Windows

Logs in Jenkins

Instance Configuration

Jenkins is ready!

Requirements

Example use case

Configuration Time

Enabling Reverse Proxy functionality

Configuring TLS/SSL

Configuring rules for response rewriting

Experiencing the dreaded "It appears that your reverse proxy set up is broken." error for yourself

Fixing the errors

Continue configuring IIS

A working web.config

Complain about it still not working

jackson2-api

正在安裝/升級 Plugins

留言

張貼留言

熱門文章

C#的out屬性

debug工作環境