Using the proxy command

2 minute read

Normally, eMake sends commands to the agents for execution. In some cases, however, it might not be desirable or possible to execute a particular command on the agents.

Proxy command location

During installation, the proxyCmd binary is installed on every host:

  • Linux: <install_dir>/i686_Linux/bin/proxyCmd where <install_dir> is /opt/ecloud by default

  • Windows: <install_dir>\i686_win32\bin\proxyCmd.exe where <install_dir> is C:\ECloud by default

When invoked by the Agent, it is: proxyCmd <program> <arg1> …​

CloudBees Build Acceleration executes < program > on the host build system and proxies the result back to the Agent so it can continue remote execution.

Determine if you can use the proxy command

You can use the “proxy command” feature to run a command locally on the eMake machine if both of the following are true :

  • You have a command that cannot run on the Agent, either because it returns incorrect results or because it is not available.

  • The command in question does not read or write build sources or output —it only makes external [outside of the build] read-only queries.

The second item is particularly important because the command runs on the host build machine, outside of the virtualized file system. Because CloudBees Build Acceleration cannot track the activity of this process, the dependency and conflict resolution mechanisms that prevent build output corruption are circumvented. It is also important that the process is read-only [that the command make no changes to whatever system it is querying] because in parallel builds with conflicts, eMake could rerun the job producing unintended side effects.

For these reasons, it is important to use the “proxy command” only when necessary. Where possible, try to ensure cluster hosts have the same tools installed as the build system.

Proxy command example 1

The simplest safe use of the proxyCmd is a source control system query. For example, a particular build step queries the source control system for branch identification using a tool called getbranch that it embeds in a version string:

foo.o: gcc -c -DBRANCH=`getbranch` foo.c

It is preferable to avoid installing and configuring a full deployment of the source control system on the host when only this simple query command is needed.

In the following example, the proxyCmd provides an efficient solution. By replacing getbranch with proxyCmd getbranch, you avoid having to install the getbranch tool and its associated components on the host:

foo.o: gcc -c -DBRANCH=`proxyCmd getbranch` foo.c

Proxy command example 2

A less invasive implementation that does not require makefile modifications and allows compatibility with non- CloudBees Build Acceleration builds is to create a link on all agent machines using the name of the tool [for example, 'getbranch'] found on the eMake host to proxyCmd. For Windows operating systems that do not support symlinks, use the copy command. When invoked under a different name, proxyCmd knows to treat the linked name as the < program > to execute:

# ln -s /opt/ecloud/i686_Linux/bin/proxyCmd /usr/bin/getbranch