Retrieve a remote file
Pulls a file from a target server back to the Clarive server. Four fields and no options. It opens a connection, copies the one file you named, and fails the job when the copy does not work.
It is the return leg of Ship File Remotely, and the usual way to bring a build artifact or a log back after Run a Remote Script produced it. For a whole directory, and for repeated transfers where only the changes matter, use Sync a Remote Directory instead.
Fields¶
Server¶
The server to fetch from. Only resources that can hold an agent appear in the picker, and the field holds one entry at a time. Picking a second resource replaces the first rather than adding to it.
The picker also lists global variables, and that is the one way to aim the op
at several servers: a variable that expands to a comma-separated string is split, and the op walks
the list in order. Every server in that list writes to the same Local Path, so the last one to run
leaves the file and the earlier ones are overwritten. Put ${hostname} into Local Path when you
want a file from each.
Two guards that Ship File Remotely has are missing here. A server resource marked inactive is skipped there with a line in the log; here it is contacted anyway and you get a connection error instead of a skip notice. An empty field fails there; here it is a silent no-op, with nothing fetched, nothing logged and the step reporting success.
User¶
The account to connect as. Left blank, the connection uses the user configured on the agent attached
to the server resource. Whatever you type goes into the log line as the part before the @, and the
part after it is the server resource's name rather than its hostname. Blank leaves the line starting
with a bare @, which is normal and not a sign the connection lost the user.
Remote Path¶
The file to fetch, as an absolute path on the target. Expanded twice: first against the
stash, then against the attributes of the server being contacted, so ${hostname}
and any custom parameter you added to the server resource resolve here.
On SSH-connected servers the path is interpreted by the target's shell, so * and ? expand there
and a pattern matching several files pulls all of them. On Clax agents the path is taken literally
and has to name one file.
A remote file that is not there fails the step and stops the job. Nothing checks the field before the connection is opened either, so a blank path gets you a failure from the target rather than a message from the form.
Local Path¶
Where the file lands on the Clarive server. Expanded under the same two-pass rule as Remote Path.
The directory has to exist already. This op does not create it, and a path pointing into a missing
directory fails with a local file error rather than anything about the remote side. Put
Run command or local script with a mkdir -p ahead of it, or point at
${job_dir}, which Init Job Home has already created.
Whether you can give a directory rather than a file name depends on the agent. SSH-connected servers accept a directory and drop the file into it under its own name. Clax agents write to the path you gave, so a directory fails to open. Naming the destination file explicitly works everywhere.
What the step leaves behind¶
Nothing in the stash. The op writes the file and logs one line per server reading
Retrieving file '*user@server*:/remote/path' to '/local/path', at info level, before the transfer
starts. There is no completion line and no byte count. The op's own return value is a bare 1, so a
Return Key on it tells you nothing about the file. To act on the contents, read the file with a
following op.
The form has none of the exist-or-skip modes that Ship File Remotely carries, and no backup or rollback setting. Any failure stops the job, so wrap it in TRY statement with CATCH statement when a missing file is an acceptable outcome.
Nothing is registered for rollback. On a rollback pass the op runs again from the start, fetching
the file a second time, unless you clear Run Rollback in the op properties.
Combining with other ops¶
The common sequence is Run a Remote Script to build or collect something on the target, this op to bring it back, then Publish local file to log to attach it to the job so it stays visible after the workspace is cleaned.
For the opposite direction use Ship File Remotely. To fetch a directory rather than a file, use Sync a Remote Directory.
If you need the same file from several servers, wrap this op in
FOREACH CI over your server list and build a distinct Local Path per
iteration. That gives you one step per server in the log and a named destination for each, which a
comma-separated variable in the Server field does not.
Examples¶
Bring a build artifact back into the job directory, which already exists by this point.
Server ${build_server}
User builduser
Remote Path ${build_temp}/${job_name}/dist.tgz
Local Path ${job_dir}/dist.tgz
Collect a log from each of several nodes without them overwriting each other. ${prod_nodes} is a
variable holding a comma-separated list.
Server ${prod_nodes}
Remote Path /var/log/myapp/deploy.log
Local Path ${job_dir}/${hostname}-deploy.log