ecremotefilecopy

3 minute readAutomation

When CloudBees CD/RO agents (on platforms other than Linux or Windows) run steps that create log files in a workspace the CloudBees CD/RO web server cannot access (through Linux or Windows agents), use ecremotefilecopy to recreate job logs so they are visible on those CloudBees CD/RO agents, which then enables the web server to retrieve and render those log files.

Using postp and ecremotefilecopy , the log file is populated and recreated in a workspace accessible to the CloudBees CD/RO web server, allowing the Job Details page to display the log file. Although this functionality is supported, it is not a recommended method of operation. This method should be used only as a last resort when a shared file system (between alternate agents and primary platform agents [Linux and Windows]) is not possible.

The reasons ecremotefilecopy is not recommended are:

  • You will not see logs in real time. Logs are not visible until the "recreate step" has completed running.

  • There is a performance penalty, especially when running with large files.

Setting up the process

  • Create a "Setup" step in your procedure

  • Update the Postprocessor field for each step whose results you want to see on the server.

  • Add a step (one or more times) to the procedure to recreate the CloudBees CD/RO server log files.

Creating a setup step

In your procedure, create a step called "Setup". This step needs to be in your procedure before any step running on a remote workspace.

This is your top-level procedure, not a subprocedure.
  • Navigate to your procedure.

  • To create a new step, click the Command step link.

  • Set the fields as follows:

Step Name: Setup

Command(s): ecremotefilecopy setup

Resource: local

Workspace: you have two choices:

  • Use default.

  • Use alternateWorkspaceForDisplay.

    There is a property on the Workspace called alternateWorkspaceForDisplay, which is a secondary location to look for workspace files. This secondary location is used when the workspace files are not accessible to the web server. If the Apache server cannot locate the file in the original workspace, it looks in the alternate one.

Update the Postprocessor field for steps in your procedure

This step defines a postprocessor that will run at the end of the steps you specify. Add the following information to every step running on a remote agent if you want to see its results in the web interface.

  • Navigate to a procedure and a step.

  • In the Postprocessor field, enter: postp --check none --loadProperty /myJob/jobSteps[Setup]/postpExtensions

  • If you are using postp in this step to scan your step log for errors, warnings, and so on also, omit "--check none" from the invocation line.

Add a final step to your procedure

This step adds a new step at the end of your existing procedure. This step finds all properties created by the postprocessor, then reads the properties and creates local log files based on the properties, then deletes the properties.

  • Navigate to your procedure.

  • To create a new step, click the Command step link.

  • Set the fields as follows:

Step Name: Recreate the Log Files

Always run step: (Check the box)

Command(s): ecremotefilecopy recreateFiles

Resource: local

Workspace: default

After the final step runs, you should see links (icons) displayed in the Log column on the Jobs Details page.

Click the icon to display the log file.

Copying other files from the workspace

By default, ecremotefilecopy copies only postp log and diag files, and step logs. You can also copy other files from the workspace using a function named postpEndHook2.

You must do the following in your step:

  1. Make sure that the file you want to copy is in the step workspace. (It can be copied there, created there, etc.)

  2. For your procedure, create a property (named postpEndHook2, for example).

  3. Define a function named postpEndHook2 inside the property. For example:

    sub postpEndHook2() { # Missing param does not cause an error $::gCommander->abortOnError(0); # Add filename to a "special" property such that it will be picked up by ecremotefilecopy my $fileName =< 'paul.txt'; copyFileToProperty ($fileName); # Restore default error handling $::gCommander->abortOnError(1); }
  4. Add the following line in the Postprocessor field of this step:

    postp --check none --loadProperty /myJob/jobSteps[Setup]/postpExtensions --loadProperty /myProcedure/postpEndHook2