Shipping and retrieving files

Leveraging SSH, Clarive Workers and ClaX (the Clarive agent), rulebooks can be used to send and receive files to and from remote servers.

Ship¶

The ship op will transfer one or more files local to the Clarive server to one or more remote servers.

This is an example of shipping a file to a remote server with SSH or ClaX (push agent). SSH requires that the host credentials be registered. For the ClaX agent, the destination server needs to have a ClaX agent installed.

Parameters:

from: - the source directory or file path
to: - the destination directory (never a filename)
worker: or host: - the destination server or worker
anchor_path (optional): a partial path, parent to the from: path

do:
    - ship:
        from: /path/file.ext
        to: /path/file.ext
        host: myhostname

The same can be accomplished with a Worker, which requires a registered Worker running with that same id:

$ cla-worker run --id myworkerid --token [token provided during registration]

do:
    - ship:
        from: /path/file.ext
        to: /path/
        worker: myworkerid

The same can be used to copy a directory and its contents:

do:
   - mkdir -p /mydir/anotherdir/
   - write_file:
        file: 'mydir/anotherdir/little_file.txt'
        body: "foo and bar"
   - ship:
       worker: myworkerid
       from: /mydir/
       to: /remote/path/

In the above the contents of the local directory /mydir/anotherdir, which is the file called little_file.txt created by us, will be copied to the server where the worker myworkerid is running.

The resulting path structure in destination will be /remote/path/anotherdir/little_file.txt.

Note

All intermediate paths will be created by the worker, but not by ClaX/SSH. You'll need to create them by running remote shell: ops.

Relative paths¶

To change how relative paths are moved around use the option anchor_path. For example:

do:
   - ship:
       worker: myworkerid
       from: /my/dir/file.txt
       to: /remote/path/
       anchor_path: /my

Will result in file.txt being copied to /remote/path/dir/file.txt. The anchor_path: option subtracts from the source parent path in from:.

Fetch¶

The fetch op retrieves a file from a remote server back to the Clarive server.

Unlike ship:, the fetch op will not retrieve directories or recurse them. Only files can be fetched. To retrieve directories from your server, run utilities such as tar or zip then fetch the tar file.

Parameters:

from: - the remote file path
to: - the destination directory (never a filename)
worker: or host: - the destination server or worker

do:
   - fetch:
       worker: myworkerid
       from: /remote/dir/file.txt
       to: /tmp/

The above will copy the remote file file.txt to the local /tmp directory.

Write File¶

Can be used to write a local or remote file.

Parameters:

file: - the destination file path.
body: - the contents of the file.
worker: or host: (option) - the destination server or worker to write the file at.

Local file:

do:
   - write_file:
       body: |
          here's a file
          with multiple lines
       file: /tmp/myfile.txt

Remote file, which will write the file directly onto the remote server:

do:
   - write_file:
       worker: myworkerid
       body: |
          here's a file
          with multiple lines
       file: /tmp/myfile.txt