Using the runagent.local file

3 minute read

The runagent.local file lets you hard-code configuration options into an agent, without modifying CloudBees files. Using the runagent.local file may become necessary to obtain specific agent behavior or to resolve certain issues. This topic discusses a few of the most common reasons for using the runagent.local file.

You must create the file in the <ECloud install>\<arch>\bin directory of the agent hosts. Then you must restart the agents.

Preventing runaway jobs

To protect against “runaway” jobs running on the cluster, the agent checks the amount of output text produced by a job. If the amount of output exceeds a threshold, then the agent sends back a portion of the output only and dumps the remainder. This prevents CloudBees Build Acceleration from consuming too many resources in the agent, on the network, and in eMake to store and transmit what is likely extraneous output.

This feature relates to only the amount of standard output text produced by a job and has nothing to do with the size of any files produced by the job. Also, this feature does not in any way affect the running of the job, only the amount of output text that is included in the log file. These “errors” are not errors at all; they are only warnings to notify you that there may be a problem with the job. If you know there is nothing wrong with the job, then you can safely ignore the warnings.

Add the following to runagent.local to change when and how this feature takes effect.

set TruncationThreshold <threshold>set TruncationLength <length>

Threshold is the number of bytes at which this feature takes effect (default is 5 MB), and length is the number of bytes to return after the feature takes effect (default is 5000 bytes).

You can verify the result by doing the following after restarting the agents:

cmtool --cm=<cm> runAgentCmd "session exec truncationparam"

Configuring stalled job detection settings

This is a Windows-only setting.

Adjust the timeout used by the agent to detect stalled commands on the agent. Add a call to the following command in the runagent.local file:

exec cmtool --cm=<cm> login <user> <password>exec cmtool --cm=<cm> runAgentCmd {agentexec timeout {{.* 120000 {cpu disk}}}}

The format of the commandTimeout value (in this instance, the argument to agentexec timeout ) is a list of the following three-element-lists:

  • A regular expression used to match the process name.

  • The amount of time with no activity after which the process is considered stalled, in milliseconds.

  • A list of the process attributes which will be monitored for activity. To monitor for activity, this must contain at least one of cpu, which means the agent will watch for CPU activity from the process; and disk, which means it will watch for I/O activity. It may contain both.

  • You can explicitly disable stalled-job detection for a process by adding an entry to the commandTimeout value with the timeout duration set to zero, or by specifying neither cpu nor disk in the attribute list.

You can verify the settings by doing the following after restarting the agents:

cmtool --cm=<cm>  runAgentCmd "agentexec timeout"

Configuring agent log rotation

CloudBees Build Acceleration automatically rotates session logs using default settings. Information about session logs:

  • stdout/stderr logs go to consoleN.log (where N is the agent number).

  • Normal session trace messages go to ecagentN.log.

  • Only session trace logs will be rotated.

  • The default size limit for log files before being rotated is 1 GB.

  • The default number of rotated files to keep is 20. When that limit is reached, the oldest log files will begin to be deleted to make space for newer logs.

  • The most recent log messages are in ecagentN.log. When the log file reaches its size limit, that file is renamed to ecagentN.log.1. If ecagentN.log.1 already exists, then it is renamed to ecagentN.log.2 before ecagentN.log is renamed to ecagentN.log.1. If ecagentN.log.2 exists, it is first renamed to ecagentN.log.3 and so on. This rotation continues until the retain count is met, at which point file deletion begins.

To configure log rotation, use the agent’s [session logger] command.

Use this format: session logger <option>

For example: session logger retaincount 10

Available log rotation options


maxfilesize <bytes>

Get or set the maximum file size for log files before they are rotated. The default is 1 GB.

filename <path>

Get or set the file name to log to.

The default for UNIX is /var/log/ecagentN.log.

The default for Windows is <install dir>\ecagentN.log (for example, C:\ECloud\ecagentN.log ).

retaincount <count>

Get or set the number of rotated log files to retain before starting to delete them.

The default is 20.

To turn off log rotation, set to 0.


Clear the contents of the ecagentN.log file. This is useful when log rotation is turned off.