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

target_sftp

Jump to bottom
Marcel Kloubert edited this page Jul 3, 2018 · 28 revisions

Home >> Targets >> sftp

SFTP

Deploys to a SFTP server.

Table of contents

  1. Settings
  2. Modes for specific files
  3. Commands
  4. Event scripts
  5. Examples

Settings [↑]

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

                "dir": "/my_package_files",
                "host": "localhost",
                "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 (auth-agent@openssh.com) for the life of the connection. agent property must also be set to use this feature. Default: (false)
alwaysAskForPrivateKeyPassphrase Always ask for private key passphrase and do not cache. 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)
askForPassword Ask for password. Default: (false)
askForPrivateKeyPassphrase Ask for private key passphrase and cache. Default: (false)
askForUser Ask for username. Default: (false)
beforeUpload* The path to an (event) script, which is executed BEFORE a file is going to be uploaded. Relative paths will be mapped to the .vscode subfolder of the workspace or the .vscode-deploy-reloaded folder inside the user's home directory.
beforeUploadOptions Options for the script defined in beforeUpload.
commands One or more commands, which should be executed on the server.
debug Activate logging for ssh2-sftp-client module and write those logs to .vscode-deploy-reloaded/.logs sub folder inside the user's home directory. Default: (false)
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 Defines the chmod access permission value for the targets files on server. s. Modes for specific files.
password The 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. Relative paths will be mapped to your home directory (.vscode-deploy-reloaded sub folder) or the .vscode folder.
privateKeyPassphrase The passphrase for the key file, if needed.
readyTimeout* How long (in milliseconds) to wait for the SSH handshake to complete. Default 20000
supportsDeepDirectoryCreation Server supports deep directory creation or not. Default: (false)
tryKeyboard Try keyboard-interactive user authentication if primary user authentication method fails. Default: (false)
uploaded* The path to an (event) script, which is executed AFTER a file has been uploaded or tried to be uploaded. Relative paths will be mapped to the .vscode subfolder of the workspace or the .vscode-deploy-reloaded folder inside the user's home directory.
uploadedOptions Options for the script defined in uploaded.
user Username. Default: anonymous

* supports placeholders

Modes for specific files [↑]

All values are octal!

{
    "deploy.reloaded": {
        "targets": [
            {
                "name:": "MY_SFTP1",
                "type": "sftp",

                "modes": {
                    "/**/*.php": 666,
                    "/**/*.txt": 777,
                }
            },

            {
                "name:": "MY_SFTP2",
                "type": "sftp",

                "modes": 777
            }
        ]
    }
}

Commands [↑]

The following example will execute commands on a Linux server:

{
    "deploy.reloaded": {
        "targets": [
            {
                "type": "sftp",
                "dir": "rm -r /var/www/my_files/*",

                "commands": {
                    "connected": [
                        "rm -r /var/www/my_files/*",

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

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

                    "uploaded": [                        
                        "chmod 664 ${remote_file}",
                        "chown ${current_bash_user} ${remote_file}"
                    ]
                }
            }
        ]
    }
}
Name Description
beforeDelete Commands to invoke BEFORE a file is going to be deleted.
beforeDownload Commands to invoke BEFORE a file is going to be downloaded.
beforeUpload Commands to invoke BEFORE a file is going to be uploaed.
connected Commands to invoke AFTER a connection has been established.
deleted Commands to invoke AFTER a file has been deleted.
downloaded Commands to invoke AFTER a file has been downloaded.
encoding The (output) encoding of the commands.
uploaded Commands to invoke AFTER a file has been uploaded.

Instead of using string values for commands, you can define setting objects, which provide more feature:

Name Description
command* The command to execute.
executeBeforeWriteOutputTo The (JavaScript) code to execute before output is written via 'writeOutputTo' setting. The result of the execution will be used as value to write.
writeOutputTo The name of the placeholder where to write the output to. The placeholder will be available for all upcoming executions.

* supports placeholders

Values

The following, additional placeholders are also supported:

Name Description Supported engine(s)
remote_dir The directory of the remote file.
remote_file The full path of the remote file.
remote_name The (base) name of the remote file.

Event scripts [↑]

beforeUpload

{
    "deploy.reloaded": {
        "targets": [
            {
                "type": "sftp",
                "name": "My SFTP folder",

                "beforeUpload": "./beforeUploadToSFTP.js",
                "beforeUploadOptions": 5979
            }
        ]
    }
}

The beforeUploadToSFTP.js file should look like that:

// s. https://code.visualstudio.com/docs/extensionAPI/vscode-api
const vscode = require('vscode');

exports.execute = async function(args) {
    // args.options === 5979 (s. 'beforeUploadOptions' above)

    // raw SFTP connection is stored in
    // args.context.connection (s. https://github.com/jyu213/ssh2-sftp-client)

    vscode.window.showInformationMessage('File ' + args.context.file + ' is going to be uploaded...');

    // return (false) if the
    // file should NOT be uploaded
};

args implements the SFTPBeforeUploadModuleExecutorArguments interface.

uploaded

{
    "deploy.reloaded": {
        "targets": [
            {
                "type": "sftp",
                "name": "My SFTP folder",

                "uploaded": "./uploadedToSFTP.js",
                "uploadedOptions": 23979
            }
        ]
    }
}

The uploadedToSFTP.js file should look like that:

// s. https://code.visualstudio.com/docs/extensionAPI/vscode-api
const vscode = require('vscode');

exports.execute = async function(args) {
    // args.options === 23979 (s. 'uploadedOptions' above)

    // raw SFTP connection is stored in
    // args.context.connection (s. https://github.com/jyu213/ssh2-sftp-client)

    if (args.context.error) {
        vscode.window.showErrorMessage('File ' + args.context.file + ' could not be uploaded: ' + args.context.error);

        return true;  // indicates that error has been
                      // handled by script and should NOT
                      // be rethrown; otherwise return nothing
    }

    vscode.window.showInformationMessage('File ' + args.context.file + ' has been uploaded.');
};

args implements the SFTPUploadedModuleExecutorArguments interface.

Examples [↑]

Using key file

{
    "deploy.reloaded": {
        "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"
            }
        ]
    }
}
Clone this wiki locally