KBEC-00077 - Agent wrapper and impersonation debug

Summary

Some ElectricFlow agent failures produce no error messages. To determine more information about the context or source of the difficulty, “wrapper debug” can be turned on.

Symptoms

Example error message:

Step error [AgentInternalError]: unable to run the command on the agent
Unspecified internal error on the agent: ecimpersonate: error reading ecwrapper pid from su output: TIMEOUT

Post-4.2 Solution on Linux and Windows

Starting from version 4.2, a java agent is introduced in ElectricFlow. The Java agent starts up and it launches the C++ agent binary directly. So the settings mentioned above is no longer valid because runAgent.sh (or runAgent.bat) is no longer called to start the C++ agent.

In order to enable impersonate debug, we need to add environment variables by adding the following lines in wrapper.conf :

set.ECWRAPPER_DEBUGFILE=ecwrapper.log
set.ECIMP_DEBUGFILE=ecimp.log
set.ECIMP_READTIMEOUT=300

Then restart the agent. If the problem reoccurs, find the ecwrapper.log.nnnnn or ecimp.log.nnnnn file in the workspace and send it to support@cloudbees.com for analysis.

This applies to Linux and Windows only. The java agent is NOT introduced in mac agents.

Solution on Mac

Add following entry to /Library/LaunchDaemons/ecmdrAgent.plist:

<key>EnvironmentVariables</key>
<dict>
<key>ECIMP_READTIMEOUT</key>
<string>300</string>
<key>ECIMP_DEBUGFILE </key>
<string>ecimp.log</string>
</dict>

Restart the agent.

Pre-4.2 Solution on Linux

Create an environment variable in the agent for debug logging. The log files will be created in the workspace directory.

1. In the ElectricFlow bin directory, by default in “/opt/electriccloud/electriccommander/bin”, edit runAgent.shto add the following lines before starting the agent:

   • to debug the wrapper (note, the value of the file ends in a “period” character):

     ECWRAPPER_DEBUGFILE=ecwrapper.log.
     export ECWRAPPER_DEBUGFILE
     

     There will be one file per step called ecwrapper.log.<jobStepId>.

   • to debug impersonation (UNIX only):

     ECIMP_DEBUGFILE=ecimp.log.
     export ECIMP_DEBUGFILE
     

     There will be one file per step called ecimp.log.<jobStepId>.

   • to extend the su impersonation time from 120 seconds (UNIX only):

     ECIMP_READTIMEOUT=300 #number of seconds to wait for su to complete
     export ECIMP_READTIMEOUT
     

2. Restart the agent (requires root access)

Pre-4.2 Solution on Windows

The solution is the same as on Linux with the following differences:

1. the file name is runAgent.bat
2. the file by default is found in “C:\Program Files\Electric Cloud\ElectricCommander\bin”