Name

Connector::Builtin::File::SCP

Description

Read/Write files to/from a remote host using SCP.

Parameters

LOCATION

The target host specification, minimal the hostname, optional including username and a base path specification. Valid examples are:

my.remote.host
otheruser@my.remote.host
my.remote.host:/tmp
otheruser@my.remote.host:/tmp

Note: If the connector is called with arguments, those are used to build a filename / path which is appended to the target specification. If you call the connector without arguments, you need to set the noargs parameter and must LOCATION point to a file (otherwise you will end up with the temporary file name used as target name).

noargs

Set to true, if you want to use the value given by LOCATION as final target. This makes additional path arguments and the file/path parameter useless.

file

Pattern for Template Toolkit to build the filename. The connector path components are available in the key ARGS. In set mode the unfiltered data is also available in key DATA. The result is appended to LOCATION. NB: For security reasons, only word, space, dash, underscore and dot are allowed in the filename. If you want to include a directory, add the path parameter instead!

path

Same as file, but allows the directory seperator (slash and backslash) in the resulting filename. Use this for the full path including the filename as the file parameter is not used, when path is set!

filemode (set mode only)

By default, the file is created with restrictive permissions of 0600. You can set other permissions using filemode. Due to perls lack for variable types, you must give this either as octal number with leading zero or as string without the leading zero. Otherwise you might get wrong permissions.

content

Pattern for Template Toolkit to build the content. The data is passed "as is". If data is a scalar, it is wrapped into a hash using DATA as key.

command, optional

Path to the scp command, default is /usr/bin/scp.

port, optional

Port to connect to, added with "-P" to the command line.

identity, optional

Path to an ssh identity file, added with "-i" to the command line.

sshconfig, optional

Path to an ssh client configuration, added with "-F" to the command line.

timeout, optional

Abort the transfer after timeout seconds.

preserve, optional

Boolean, adds the "-p" option to the scp command (some servers seem to require this to carry over the permissions).

Supported Methods

set

Write data to a file.

$conn->set('filename', { NAME => 'John Doe', 'ROLE' => 'Administrator' });

See the file parameter how to control the filename.

get

Fetch data from a file. See the file parameter how to control the filename.

my $data = $conn->set('filename');

Example

my $conn = Connector::Builtin::File::SCP->new({
   LOCATION => 'localhost:/var/data',
   file => '[% ARGS.0 %].txt',
   content => ' Hello [% NAME %]',
   filemode => 0644
});

$conn->set('test', { NAME => 'John Doe' });

Results in a file /var/data/test.txt with the content Hello John Doe.

A note on security

To enable the scp transfer, the file is created on the local disk using tempdir/tempfile. The directory is created with permissions only for the current user, so no other user than root and yourself is able to see the content. The tempfile is cleaned up immediatly, the directory is handled by the internal garbage collection.