Upgrading Agents for BuildMaster 4.0

This document only applies to users upgrading from BuildMaster v3, and is a companion to Upgrading from BuildMaster v3 and v4.

For BuildMaster 4.0, we have taken advantage of the major version change to make several breaking changes that prevent BuildMaster from automatically updating 3.x agents:

• BuildMaster Agents now require .NET 4.0 instead of .NET 2.0
• The WCF self-hosted SOAP agent (deprecated in favor of the TCP self-hosted agent) has been removed
• The Linux Mono-based SOAP agent (deprecated in favor of SSH-based agents) has been removed

Upgrading an IIS-Hosted SOAP Agent

This type of agent is still officially supported, but will need a manual reinstallation:

1. Uninstall the old agent from the remote server – do not delete it from the Servers page within BuildMaster
2. Ensure that .NET 4 is installed and ASP.NET 4 has been registered with IIS
3. Install the new agent

Upgrading a Self-Hosted TCP Agent

This type of agent is still officially supported, but will need a manual reinstallation:

1. Uninstall the old agent from the remote server – do not delete it from the Servers page within BuildMaster
2. Ensure that .NET 4 is installed
3. Install the new agent – visit the documentation on the subject for more information and tips for silent/scripted installation

Upgrading a Self-Hosted SOAP (WCF) Agent

This type of agent has been deprecated and removed from agent installers since BuildMaster 3.3, but BuildMaster continued to keep existing agents of this type up-to-date in versions prior to 4.0.

1. Choose which type of agent to use instead. See KB1039 for a comparison of the agent types.
2. Depending on which agent you have chosen, follow the steps in one of the above sections of this article to remove the old agent and install the new one.
3. Follow the "Converting from Self-Hosted SOAP (WCF) to the Self-Hosted TCP Agent" instructions below to change the agent type from BuildMaster's perspective.

Upgrading a Linux Mono Agent

This type of agent has been deprecated since BuildMaster 3.2 in favor of an SSH-based agent that requires no installed components on the Linux server.

1. Remove the Mono agent from your Linux server.
2. Ensure that your server is configured to accept SSH connections.
3. Add an SSH-based agent to BuildMaster.

Converting from Self-Hosted SOAP (WCF) to the Self-Hosted TCP Agent

Because the self-hosted SOAP (WCF) agent has been removed in BuildMaster 4.0, it will need to be uninstalled and the new self-hosted TCP agent will need to be installed on the remote server as a replacement. Note: you should not delete the agents from within BuildMaster itself, otherwise you would need to update all deployment plans that rely on that server! 

Once you have installed the new self-hosted TCP agent on the remote server, you will need to convert your agents on the BuildMaster side. To do so, visit the Administration overview page, and select "Execute a System Recipe", choose the "Change Agent Types (TCP-SOAP)" option, and leave the default dropdown option of "Agent Conversion Types: From SOAP to TCP Agent". By default, only SOAP agents are shown – so if you do not see the server in the list, it is already a TCP-based agent. Note: be sure to only choose servers with the self-hosted (i.e. Windows Service hosted) SOAP agents, if you are hosting your agents with IIS leave them unchecked so they remain SOAP agents. 

Once you've selected the correct SOAP agents to convert, choose "Convert Agents" to convert them and return to the server overview page:

Once converted, it can take up to a few minutes to update the server overview page because the status values on that page are cached. To check the live status of a server, select the server from the overview page, and examine the Agent Status section at the bottom of that page.

Also note that the "Hosted" property simply indicates that the type of agent (in this case, the self-hosted TCP-based agent) is a type of agent that is installed on the server – it does not know whether that is actually the case or not unless the "Status" field indicates something other than "Error" or "Inactive".

Troubleshooting Agents in ERROR Status

Agents can be put in ERROR status for a variety of reasons, the most common are:

• The wrong type of agent is installed on the server – verify that the type of agent that BuildMaster identifies, is actually what is installed on the server (e.g. Self-hosted (TCP) Agent should have a service installed on the remote server, and IIS-hosted (SOAP) Agent should have a website configured in IIS on the remote server). This problem commonly results in error messages in the BuildMaster Error Log indicating such a problem.
• For the self-hosted agent, the agent service (INEDOBMAGT) is not running
• For the IIS-agent, either the hosting website or application pool are stopped
• There is a firewall blocking the port of the agent
• There is a newer agent installed on the remote server than the current installation of BuildMaster. Always make sure to match the version of the agent with that of the BuildMaster installation when freshly installing or manually upgrading the agent

Testing connection to an IIS-Hosted (SOAP) agent:

To test whether a SOAP agent is accessible by BuildMaster, browse to http://agent-server:port/agent.asmx from the BuildMaster server. If you see a page similar to the below image, the connection is available:

If you do not see this page, try connecting locally from the agent server itself – this will indicate whether the network is the culprit.

Testing connection to a Self-Hosted (TCP) agent:

To whether a TCP agent is accessible by BuildMaster, open a telnet session to the server and port:

telnet agent-server [port]

If the connection is successful, there will be a blank prompt and you can send text to the agent. If the connection is unsuccessful, you would see an error message similar to: "Connecting To agent-server...Could not open connection to the host, on port 1000: Connect failed".