Skip to content
This repository has been archived by the owner on Jul 1, 2021. It is now read-only.

target_sftp

Jump to bottom
Marcel Kloubert edited this page Mar 17, 2018 · 69 revisions

Home >> Targets >> sftp

SFTP

Deploys to a SFTP server.

Demo SFTP

{
    "deploy": {
        "targets": [
            {
                "type": "sftp",
                "name": "My SFTP folder",
                "description": "A SFTP folder",

                "dir": "/my_package_files",
                "host": "localhost", "port": 22,
                "user": "tester", "password": "password"
            }
        ]
    }
}
Name Description
agent* Name or path to ssh-agent for ssh-agent-based user authentication. s. ssh2 module
agentForward Set to (true) to use OpenSSH agent forwarding ([email protected]) for the life of the connection. agent property must also be set to use this feature. Default: (false)
alwaysAskForPassword Always ask for password and do not cache, if no password is defined. Default: (false)
alwaysAskForUser Always ask for username and do not cache, if no user is defined. Default: (false)
beforeUpload One or more command to execute on the server BEFORE a file is going to be uploaded.
checkBeforeDeploy Check for newer files before a deployment starts or not. Default: (false)
closing One or more command to execute on the server BEFORE a connection is going to be closed.
connected One or more command to execute on the server AFTER a connection has been established.
dir* The remote directory on the server. Default: /
hashAlgorithm The algorithm to use to verify the fingerprint of a host. Default: md5
hashes The optional list of one or more fingerprints, that are used to verify the host. If not defined any host will be accepted.
host The host address of the server. Default: 127.0.0.1
modes An octal value that defines the chmod access permission value for the targets files on server. This can also be an object: The properties are regular expressions that checks the target file (or directory) path and if matching, the value of a matching property will be used as access value (s. Modes for specific files).
noCommandOutput Default value if output of commands should NOT be fetched. Default: (true)
password Password
port The TCP port of the server. Default: 22
privateKey* The path to the private key file, if authentification should be done via SSH key.
privateKeyPassphrase The passphrase for the key file, if needed.
privateKeySourceFormat* The source format of the private key. s. node-sshpk
privateKeyTargetFormat* The target format of the private key. s. node-sshpk
promptForPassword Prompt for a password if not defined (or for privateKeyPassphrase, if privateKey is set). Default: (true)
readyTimeout How long (in milliseconds) to wait for the SSH handshake to complete. Default 20000
transformer* The path to the script that transforms data before it is send / after it has been downloaded.
transformerOptions Optional data for the transformer script.
tryKeyboard Try keyboard-interactive user authentication if primary user authentication method fails. Default: (false)
unix [[Settings
uploaded One or more command to execute on the server AFTER a file has been uploaded.
updateModesOfDirectories Also execute 'chmod' for the directory of a file (s. modes). Default: (false)
user Username. Default: anonymous

* supports placeholders

unix

Settings for Linux/UNIX based targets.

Name Description
convertCRLF Convert CR+LF (\r\n) to LF (\n) in text files for target or not. Default: (false)
encoding The encoding (like ascii or utf8) for the conversion to use (s. Buffer.toString() for more information). Default: ascii

Examples

Using key file

{
    "deploy": {
        "targets": [
            {
                "type": "sftp",
                "name": "My SFTP folder",
                "description": "SFTP target with key file",

                "dir": "/my_package_files",
                "host": "localhost",

                "user": "mkloubert",
                "privateKey": "/.ssh/id_rsa"
            }
        ]
    }
}

Modes for specific files

{
    "deploy": {
        "targets": [
            {
                "type": "sftp",

                "host": "myhost.examples.com",
                "dir": "/my_package_files",

                "user": "tester", "password": "P@ssword123!",

                "modes": {
                    "(\\.html)$": 777,
                    "(\\.php)$": 666,
                }
            }
        ]
    }
}

Execute commands on server

The following example will execute commands on a Linux server:

  1. Executes rm command AFTER connection has been established (connected)
  2. Executes rm command BEFORE a file is uploaded (beforeUpload)
  3. Executes touch command AFTER a file has been uploaded (uploaded)
  4. Then executes chmod command (uploaded)
  5. Executes chown command BEFORE connection is going to be closed (closing)
{
    "deploy": {
        "targets": [
            {
                "type": "sftp",

                "host": "myhost.examples.com",
                "dir": "/var/www/my_package_files",

                "user": "tester", "password": "P@ssword123!",

                "connected": [
                    "rm -r /var/www/my_package_files/*",

                    {
                        "command": "whoami",
                        "writeOutputTo": "current_bash_user",
                        "executeBeforeWriteOutputTo": "$others['current_bash_user'].trim()"
                    }
                ],

                "beforeUpload": [
                    "rm ${remote_file}"
                ],

                "uploaded": [
                    "touch -t ${mtime_touch} ${remote_file}",
                    "chmod ${mode} ${remote_file}"
                ],

                "closing": [
                    {
                        "command": "chown -R ${current_bash_user} /var/www/my_package_files/*",
                        "verbose": true
                    }
                ]
            }
        ]
    }
}

A command (entry) can be a string or an object with settings:

Name Description
command The command to execute.
executeBeforeWriteOutputTo The code to execute before output is written via writeOutputTo setting. The result of the execution will be used as value to write.
noOutput Indicates if output of that command should NOT be fetched. The default value is defined in the noCommandOutput setting of the target.
outputEncoding The encoding for the execution output to use. Default: utf8
verbose Output execution or not. Default: (false)
writeOutputTo The name of the placeholder where to write the output to. This value will be available for all upcoming commands, but will be available for the current deployment only.

beforeUpload / uploaded

The following placeholder / variables are supported:

Name Description Example
atime_iso The access time of the local file in ISO format. 2017-04-19T12:55:52.356Z
atime_iso_utc The UTC access time of the local file in ISO format. 2017-04-19T12:55:52.356Z
atime_touch The access time of the local file in touch format. 201704191255.52
atime_touch_utc The UTC access time of the local file in touch format. 201704191255.52
atime_unix The access time of the local file in UNIX format. 1492606552
atime_unix_utc The UTC access time of the local file in UNIX format. 1492606552
birthtime_iso The birth time of the local file in ISO format. 2017-04-19T12:55:52.356Z
birthtime_iso_utc The UTC birth time of the local file in ISO format. 2017-04-19T12:55:52.356Z
birthtime_touch The birth time of the local file in touch format. 201704191255.52
birthtime_touch_utc The UTC birth time of the local file in touch format. 201704191255.52
birthtime_unix The birth time of the local file in UNIX format. 1492606552
birthtime_unix_utc The UTC birth time of the local file in UNIX format. 1492606552
ctime_iso The change time of the local file in ISO format. 2017-04-19T12:55:52.356Z
ctime_iso_utc The UTC change time of the local file in ISO format. 2017-04-19T12:55:52.356Z
ctime_touch The change time of the local file in touch format. 201704191255.52
ctime_touch_utc The UTC change time of the local file in touch format. 201704191255.52
ctime_unix The change time of the local file in UNIX format. 1492606552
ctime_unix_utc The UTC change time of the local file in UNIX format. 1492606552
gid The owner's group ID of the local file. 100
mode The file mode (octal) of the local file. 666
mode_full The full file mode (octal) of the local file. 100666
mode_decimal The file mode (decimal) of the local file. 33206
mtime_iso The modified time of the local file in ISO format. 2017-04-19T12:55:52.356Z
mtime_iso_utc The UTC modified time of the local file in ISO format. 2017-04-19T12:55:52.356Z
mtime_touch The modified time of the local file in touch format. 201704191255.52
mtime_touch_utc The UTC modified time of the local file in touch format. 201704191255.52
mtime_unix The modified time of the local file in UNIX format. 1492606552
mtime_unix_utc The UTC modified time of the local file in UNIX format. 1492606552
remote_dir The path of the remote directory. /wwwroot/docs
remote_file The path of the remote file. /wwwroot/docs/test.html
remote_name The (base) name of the remote file. test.html
uid The owner's user ID of the local file. 85
user The name of the user as defined in the settings. tester

closing / connected

The following placeholder / variables are supported:

Name Description Example
close_time_iso1 The close time in ISO format. 2017-04-19T12:55:52.356Z
close_time_iso_utc1 The UTC close time in ISO format. 2017-04-19T12:55:52.356Z
close_time_touch1 The connection time in touch format. 201704191255.52
close_time_touch_utc1 The UTC close time in touch format. 201704191255.52
close_time_unix1 The connection time in UNIX format. 1492606552
close_time_unix_utc1 The UTC close time in UNIX format. 1492606552
connected_time_iso The connection time in ISO format. 2017-04-19T12:55:52.356Z
connected_time_iso_utc The UTC connection time in ISO format. 2017-04-19T12:55:52.356Z
connected_time_touch The connection time in touch format. 201704191255.52
connected_time_touch_utc The UTC connection time in touch format. 201704191255.52
connected_time_unix The connection time in UNIX format. 1492606552
connected_time_unix_utc The UTC connection time in UNIX format. 1492606552
user The name of the user as defined in the settings. tester

1: only available for closing

Clone this wiki locally