How to configure an outbound proxy for a Bamboo Remote Agent
Platform notice: Server and Data Center only. This article only applies to Atlassian products on the Server and Data Center platforms.
Support for Server* products ended on February 15th 2024. If you are running a Server product, you can visit the Atlassian Server end of support announcement to review your migration options.
*Except Fisheye and Crucible
Summary
This guide specifically covers configuring an outbound proxy for the Bamboo Remote Agent java process. This means outbound HTTP and Java Message Service traffic from the agent to the Bamboo Agent (typically to the Bamboo master) will go via the proxy or port forwarding rule. This configuration does not apply to any build tasks which forks an external process to complete its work, for example, Maven and Git (and many others). Each tool typically has its own method for defining a proxy:
When the Bamboo master can only be reached by a remote agent via a forward proxy, the agent must be configured to route traffic to the master via this proxy. This article will show you where to configure the generic Java proxy arguments for a Bamboo Remote Agent.
Proxy authentication is available on Bamboo 9.0.0 and later. Please check for details and fixed releases.
- BAM-21240 - Getting issue details... STATUS
Solution
The Bamboo Remote Agent uses two types of connection, one being HTTP – the one you can use an outbound HTTP proxy, and a Java Message Service (JMS) connection – used to connect the Agent to Bamboo's ActiveMQ service.
HTTP proxy
Refer to the generic knowledge-base article for Atlassian applications to understand the different parameters that can be configured and how they work: How to Configure Outbound HTTP and HTTPS Proxy for your Atlassian application
- Edit
$BAMBOO_AGENT_HOME/conf/wrapper.conf Add the arguments as additional parameters. Each additional must be numbered sequentially. Additionals that are commented out can be ignored from the sequence. E.g
wrapper.java.additional.1=-Dbamboo.home=/home/bamboo/bamboo-agent-home wrapper.java.additional.2=-Dbamboo.agent.ignoreServerCertName=false #wrapper.java.additional.3=-Dlog4j.configuration= #wrapper.java.additional.3=-agentlib:yjpagent wrapper.java.additional.3=-Dhttp.proxyHost=proxy.mydomain.net wrapper.java.additional.4=-Dhttp.proxyPort=3128 wrapper.java.additional.5=-Dhttps.proxyHost=proxy.mydomain.net wrapper.java.additional.6=-Dhttps.proxyPort=3128Restart the agent
Java Message Service (JMS) proxy
The JMS connection uses a pure TCP connection between the Remote Agent and Bamboo Server on default ports 54663/TCP and 54667/SSL. To know more about how the JMS service works in Bamboo please check the following KB:
If you wish to proxyfy the JMS connection, you can check the options below.
Set a firewall rule to port forward the TCP port
This is not a proxy solution at all, but an alternative. You will need to allow traffic from the Remote Agent to hit your Bamboo server directly on the JMS port.
Configure an L4 TCP proxy pointing to your Bamboo Server JMS port
The proxy needs to forward TCP L4 traffic directly to your Bamboo server on the Bamboo Broker JMS port. It is also necessary to modify the Broker client URL property in Bamboo to point to your TCP proxy address. The Broker client URL (not to be confused with the Broker URL) is used by the Bamboo Remote Agents to know where to send the JMS traffic.
- Bamboo administration -> Overview -> System -> General configuration
- Alternatively, you can modify the Bamboo Broker client URL by changing the value of
bamboo.jms.broker.urion$BAMBOO_HOME/bamboo.cfg.xmlfile in your Bamboo Server - Changes to the Client Broker URL and Broker URL require a full restart of the Bamboo Server
Use a SOCKS proxy
Though functional, the use of a SOCKS proxy is discouraged as we don't have enough usage reports from customers and we don't test this sort of configuration as part of Bamboo active development and it may not scale for large amounts of traffic.
A Remote Agent connection to the ActiveMQ Broker via a SOCKS proxy tunnel only works when using the following protocols within the Bamboo Broker Client URI:
TCP
- SSL
- NIO+SSL
NIO- Broken do not use, see below.
Though ActiveMQ client-side would instantiate a regular TCP transport when using NIO, using that results in a malformed SOCKS connection being established and getting dropped. Do not use NIO as an ActiveMQ Client transport.
As you will be using a proxy, it is highly recommended to implement an SSL connection between both JMS endpoints to prevent tampering. When using SSL, the SOCKS proxy switches to CONNECT mode and establishes an end-to-end tunnel between both peers and allow unmodified traffic between them with privacy.
Please refer to the Securing your remote agents documentation to understand how to prepare your Bamboo Server to accept SSL connections on the ActiveMQ service.
Please validate the ability of your SOCKS server to manage clear-text traffic before applying the configuration to a production environment.
As ActiveMQ does not yet support configuring a SOCKS proxy only for JMS traffic, you will need to set it globally in Java. Using a SOCKS proxy will have an effect on all outbound traffic leaving the Agent JVM. You can optionally set an HTTP(s) proxy or use Java -DsocksNonProxyHosts and -Dhttp.nonProxyHosts as exclusion rules.
To use a SOCKS proxy:
- Edit
$BAMBOO_AGENT_HOME/conf/wrapper.conf Add the arguments as additional parameters. Each additional must be numbered sequentially. Additionals that are commented out can be ignored from the sequence. E.g
wrapper.java.additional.1=-Dbamboo.home=/home/bamboo/bamboo-agent-home wrapper.java.additional.2=-Dbamboo.agent.ignoreServerCertName=false #wrapper.java.additional.3=-Dlog4j.configuration= #wrapper.java.additional.3=-agentlib:yjpagent wrapper.java.additional.4=-DsocksProxyHost=socks.mydomain.net wrapper.java.additional.5=-DsocksProxyPort=1080Restart the agent
You can also combine both HTTP proxy and SOCKS proxy options on the same agent configuration, or just use SOCKS for everything including HTTP and direct connections as shown above.