Skip to end of metadata
Go to start of metadata

There are several background jobs in Jenkins which try and reach out on the Internet during normal operation. While this isn't an issue as long as the machine you're running Jenkins on has direct Internet access, it can lead to all kind of (sometimes inconsistent) issues as soon as the only way to get out on the Internet from Jenkins' perspective is an HTTP and / or HTTPS proxy server. This page tries to provide an overview and is supposed to help people who want to make sure they can use Jenkins properly behind a proxy server.

Background: What kind of proxy?

In order to understand your problem, you may want to find out what kind of proxy is deployed in your network. Actually, there are different major flavors of proxies and some of them come with subtle differences in individual implementations.

Please note that NAT (Network Address Translation) is not a proxy. In case your network just uses NAT to access the Internet, you should be fine and can stop reading here.

Just especially in larger and sometimes more conservative organizations network administrators think that access to the Internet needs to be mediated to say the least. As simple NAT does not provide any means of either filtering any content or of doing any caching, HTTP(S) proxies are usually introduced. If you can access you browser's network connection settings and there is anything configured like "HTTP proxy: some.proxy.net:1234" then you seem to be using an HTTP(S) proxy. Also in case there is any automated proxy configuration (proxy.pac or "determine proxy settings automatically") the automatically configured setup will most likely involve an HTTP(S) proxy.

How to find out the address and port number of your proxy to use is an exercise left to the reader. Use your preferred search engine if you have no idea how to find this out or ask your network administrator for more information.

Disclaimer:

Nothing explained on this page is meant to circumvent any policies that the network administrator has set or to access any content from the Internet which you couldn't also access using your web browser. The whole purpose of making Jenkins talk through proxies directly through the Internet is convenience. For example, Jenkins has a very convenient update mechanism for plugins. Any running instance of Jenkins will check the plugin repository on the Internet for newly available or updated plugins and allow you to install or update a plugin with just a mouse click. If Jenkins cannot achieve that because it cannot pass the proxy server and cannot reach out on the Internet, you could achieve the same by manually downloading the plugins and installing them. It means just more work for you.

How Jenkins handles Proxy Servers

You can configure the proxy server that Jenkins will use by going to Manage Jenkins > Manage Plugins > Advanced. This is preferred over setting JVM properties.

Here's a screenshot showing an example configuration:

Field

Description

Server

Host name or address of the proxy server. Example: proxy.example.com

Port

The port the proxy server listens on. Example: 8080

User name

If the proxy server requires authentication, enter the name of the user here.

Password

If the proxy server requires authentication, enter the password here.

No Proxy Host

If certain hosts must be contacted directly (without going through the proxy), you can specify their names here. You can even use * as a wildcard. Example: *jenkins-test*.example.com

Test URL

Enter the full URL of a host to use for testing the proxy configuration. Example: http://jenkins-ci.org/

To temporarily disable the proxy configuration, you can add a single wildcard character * on the first line. Erasing the value of Server will discard all values and disable the use of a proxy server.

Which plugins support a proxy server?

  • No labels

7 Comments

  1. Is it really true that one has to use -DhttpProxyHost instead of JVM default -Dhttp.proxyHost?

    I haven't found httpProxyHost on the Jenkins source code grepping it!

    1. The code snippet is completely wrong here. What he wanted to writ is:

      java -Dhttp.proxyHost=some.proxy.host -Dhttp.proxyPort=1234 -jar jenkins.war
      

      and

      java -Dhttp.proxyHost=some.proxy.host -Dhttp.proxyPort=1234 -Dhttps.proxyHost=some.otherorsame.host -Dhttps.proxyPort=2345 -jar jenkins.war
      

      Those settings work. I've tested them. These are the common JVM proxy settings.

  2. I set proxy in "Manage Jenkins" -> "Manage Plugins" -> "Advanced", and the job also uses this proxy to checkout (Git Plugin) code.

    So I think not only plugin manager using this setting.

    Started by user chenyang
    Building on master in workspace /var/lib/jenkins/workspace/performance
    Cloning the remote Git repository
    Cloning repository https://github.com/sp-chenyang/performance.git
     > git init /var/lib/jenkins/workspace/performance # timeout=10
    Fetching upstream changes from https://github.com/sp-chenyang/performance.git
     > git --version # timeout=10
    Setting http proxy: 192.168.2.207:8080
     > git fetch --tags --progress https://github.com/sp-chenyang/performance.git +refs/heads/*:refs/remotes/origin/*
     > git config remote.origin.url https://github.com/sp-chenyang/performance.git # timeout=10
     > git config --add remote.origin.fetch +refs/heads/*:refs/remotes/origin/* # timeout=10
     > git config remote.origin.url https://github.com/sp-chenyang/performance.git # timeout=10
    Fetching upstream changes from https://github.com/sp-chenyang/performance.git
    Setting http proxy: 192.168.2.207:8080
     > git fetch --tags --progress https://github.com/sp-chenyang/performance.git +refs/heads/*:refs/remotes/origin/*
     > git rev-parse refs/remotes/origin/master^{commit} # timeout=10
     > git rev-parse refs/remotes/origin/origin/master^{commit} # timeout=10
    Checking out Revision adb37dd84038a554fba1a5e9d513acadaccb49dd (refs/remotes/origin/master)
     > git config core.sparsecheckout # timeout=10
     > git checkout -f adb37dd84038a554fba1a5e9d513acadaccb49dd
    
  3. Anything for automatic configuration script? 

  4. Please let me know code for automation. -Dhttp.proxyHost=some.proxy.host -Dhttp.proxyPort=1234 -Dhttps.proxyHost=some.otherorsame.host -Dhttps.proxyPort=2345 does not work and even if works, in Advanced tab, it's empty.

  5. What is the meaning of "the proxy server that Jenkins will use"? I want to deploy jenkins behind a proxy, meaning that the clients are accessing one server and that server handles the proxying (reverse proxy) so that the user can use "jenkins.server.com" but Jenkins is running on some local server with only a local IP.

    Is this the proper page to read then?

    1. The proxy server, that this page refers to, is the one for outgoing webrequests originating from the jenkins server. For some functions Jenkins will contact web resources over http(s). On networks that feature a proxy normal web traffic is blocked unless it flows through the proxy. Deploying jenkins behind a proxy is the other direction so to answer your question; no this is not the proper page.

      You probably want to take a look at Jenkins says my reverse proxy setup is broken