npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

grunt-ssh

v0.12.9

Published

SSH and SFTP tasks for Grunt

Downloads

5,449

Readme

New owner! Starting 12-23-2015, I (@israelroldan) am standing on the shoulders of two giants (@chuckmo and @andrewrjones) as maintainer of this project. Contributions are welcome as always. (This message will be removed on next release as well).

grunt-ssh

Build Status NPM version Dependencies

SSH and SFTP tasks for Grunt, using a pure JS implementation of ssh2.

Overview

This plugin requires Grunt ~0.4.0

If you haven't used Grunt before, be sure to check out the Getting Started guide, as it explains how to create a Gruntfile as well as install and use Grunt plugins. Once you're familiar with that process, you may install this plugin with this command:

npm install grunt-ssh --save-dev

Once the plugin has been installed, it may be enabled inside your Gruntfile with this line of JavaScript:

grunt.loadNpmTasks('grunt-ssh');

This library provides two Grunt tasks for ssh:

  • sftp
  • sshexec

This plugin was designed to work with Grunt 0.4.x. If you're still using grunt v0.3.x it's strongly recommended that you upgrade, but in case you can't please use v0.1.0.

Synopsis

// don't keep passwords in source control
secret: grunt.file.readJSON('secret.json'),
sftp: {
  test: {
    files: {
      "./": "*json"
    },
    options: {
      path: '/tmp/',
      host: '<%= secret.host %>',
      username: '<%= secret.username %>',
      password: '<%= secret.password %>',
      showProgress: true
    }
  }
},
sshexec: {
  test: {
    command: 'uptime',
    options: {
      host: '<%= secret.host %>',
      username: '<%= secret.username %>',
      password: '<%= secret.password %>'
    }
  }
}

An example secret.json might look like:

{
    "host" : "myhost",
    "username" : "username",
    "password" : "**************"
}

Or, specifying SSH configurations for re-use, and referencing from tasks:

// don't keep passwords in source control
sshconfig: {
  "myhost": grunt.file.readJSON('myhost.json')
},
sshexec: {
  test: {
    command: 'uptime',
    options: {
      config: 'myhost'
    }
  },
  ls: {
    command: 'ls -la',
    options: {
      config: 'myhost'
    }
  }
}

You can also overwrite the username, password, passphrase or config at runtime as a command line option:

$ grunt sshexec:someTask --config myhost --username foo

Description

sftp

Copies one or more files to a remote server over ssh.

Inside your grunt.js file add a section named sftp.

Parameters

files object

The files to copy. Should contain key:value pairs.

If you would like to upload multiple files, use an array. For example:

files: {
  "./": ["<%= dirs.css %>style.css","<%= dirs.css %>login.css","<%= dirs.css %>print.css"]
},

The following will not work:

files: {
  "./": "<%= dirs.css %>style.css",
  "./": "<%= dirs.css %>login.css",
  "./": "<%= dirs.css %>print.css"
},
options object
path string

The path on the remote server. Defaults to /.

minimatch object

Options for minimatch.

username string

The username to authenticate as on remote system.

host string

The remote host to copy to, set up in your ~/.ssh/config.

port number

The remote port, optional, defaults to 22.

srcBasePath string

Optionally strip off an initial part of the file when performing the SFTP operation. This is a string operation, so trailing slashes are important.

For example:

    /* [...] */
    files: {
      "./": "dist/**"
    },
    options: {
      path: '/tmp/',
      /* [...] */
      srcBasePath: "dist/"

Would SFTP the files in dist directly into tmp (eg. dist/index.html ==> /tmp/index.html)

createDirectories boolean

Optionally check whether the directories files will be sftp'd to exist first. This can take a bit of extra time as directories need to be checked, so this option is disabled by default.

See also the directoryPermissions option.

directoryPermissions number

The permissions to apply to directories created with createDirectories. The default is 0755. JSHint will probably yell at you unless you set this using parseInt:

directoryPermissions: parseInt(755, 8)
showProgress boolean

Show a progress bar during the file transfer. The default is false.

chunkSize integer

Size of each read in bytes (default: 32768)

callback function

Callback function called after command execution. Default: empty function

Connection options

There are three mutually exclusive sets of connection options. They are privateKey (with optional passphrase), password, and agent. If any of these options are private, they will be tried exclusively, and other connection options will be ignored. Each is described a bit more below.

privateKey string

A string containing the contents of the private key to use to authenticate with the remote system, you can load this from a file using grunt.file.read. Be careful you don't put this into source control unless you mean it!

If a privateKey and passphrase are required, they

options: {
  privateKey: grunt.file.read("id_rsa"),
  passphrase: <%= secret.passphrase %>
}
passphrase string

The passphrase to use with the privateKey. As per the privateKey, do not expose this in your Gruntfile or anywhere that'll end up public unless you mean it, load it from an external file.

password string

The password to authenticate on remote system.

agent string

Path to ssh-agent's UNIX socket for ssh-agent-based user authentication.

options: {
         host: '<%= pkg.host %>',
         port: '<%= pkg.port %>',
         username: '<%= pkg.username %>',
         agent: process.env.SSH_AUTH_SOCK
}

If you use jshint, remember to add process: true in globals

readyTimeout integer

How often (in milliseconds) to wait for the SSH handshake to complete.

sshexec

Runs a command over ssh.

NOTE: To see the output of your sshexec command locally, use the --verbose flag.

Inside your grunt.js file add a section named sshexec.

Parameters

command string or array

The command or commands to run, if an array is supplied, all the commands are executed on the same connection.

options object
username string

The username to authenticate as on remote system.

host string

The remote host to copy to, set up in your ~/.ssh/config.

port number

The remote port, optional, defaults to 22.

pty boolean/object

Set to true to allocate a pseudo-tty with defaults, or an object containing specific pseudo-tty settings (see 'Pseudo-TTY settings'). Setting up a pseudo-tty can be useful when working with remote processes that expect input from an actual terminal (e.g. sudo's password prompt).

ignoreErrors boolean

Determins if the task should stop or continue if any of the commands returns a code other than 0. Disabled by default.

suppressRemoteErrors boolean

If true only display remote error messages if Grunt is run with the --verbose flag.

Connection options

There are three mutually exclusive sets of connection options. They are privateKey (with optional passphrase), password, and agent. If any of these options are private, they will be tried exclusively, and other connection options will be ignored. Each is described a bit more below.

privateKey string

A string containing the contents of the private key to use to authenticate with the remote system, you can load this from a file using grunt.file.read. Be careful you don't put this into source control unless you mean it!

options: {
  privateKey: grunt.file.read("id_rsa"),
  passphrase: <%= secret.passphrase %>
}
passphrase string

The passphrase to use with the privateKey. As per the privateKey, do not expose this in your Gruntfile or anywhere that'll end up public unless you mean it, load it from an external file.

password string

The password to authenticate on remote system.

agent string

Path to ssh-agent's UNIX socket for ssh-agent-based user authentication.

options: {
         host: '<%= pkg.host %>',
         port: '<%= pkg.port %>',
         username: '<%= pkg.username %>',
         agent: process.env.SSH_AUTH_SOCK
}

If you use jshint, remember to add process: true in globals

readyTimeout integer

How often (in milliseconds) to wait for the SSH handshake to complete.

Note

sshexec runs each command individually, and it does not keep state of the previous command, so when you need to perform 2 commands or more , you could do e.g.:

sshexec: {
  test: {
    command: ['sh -c "cd /; ls; pwd"'],
    options: {
      host: '<%= secret.host %>',
      username: '<%= secret.username %>',
      password: '<%= secret.password %>'
    }
  }
}

Links

Release History

  • 2015/02/07 - v0.12.1 - #92 Fixed ssh2 dependency to version 0.3.x (bostrom (Fredrik Boström))
  • 2014/09/11 - v0.12.0 - #70: Ensure empty directories are created (Robert Price); #71: Enables forwarding of the authentication agent connection (Yannis Sgarra); #73: Downloading files (sheo13666); #75: Doc fix (Alexander Afanasiev).
  • 2014/06/04 - v0.11.2 - #63: sftp improvements (Brian White; #64: Changed error handling for SFTP junglebarry
  • 2014/03/21 - v0.11.1 - #59: Don't add '/' to empty path (David J. Bradshaw).
  • 2014/03/15 - v0.11.0 - #50: Enable setting of chunkSize option (Michael Lam); #51: Fix bad output on close (Eric Kever); #56: Add readyTimeout option for ssh2 connections (calebTomlinson).
  • 2014/01/16 - v0.10.0 - #47: Add an optional progress bar for sftp uploads (Jason Williams).
  • 2013/12/06 - v0.9.1 - #44: Improve doc for SSH connection options (Mark Stosberg); #45: Fix incorrect Connection parameter in execCommand (jabes).
  • 2013/12/06 - v0.9.0 - #28: Pseudo-TTY support; #40: Add trailing slash to path if needed; #31: Print debug messages from ssh2 when --debug option is passed; Use latest version of ssh2 (0.2.14).
  • 2013/11/17 - v0.8.0 - #33: File counter for sftp and suppressRemoteErrors option for sshexec (David J. Bradshaw); #34: Use stat() instead of opendir() for checking existence of a dir (Harri Hälikkä); #38: Doc updates (Alexandre Richonnier).
  • 2013/10/17 - v0.7.0 - #32: Added command line options for username, password and passphrase (David J. Bradshaw); Doc updates.
  • 2013/09/25 - v0.6.2 - Allow sftp task to use the shared sshconfig; Allow overriding sshconfig properties in the task config (Andy Royle). Document using the private key with sshexec.
  • 2013/07/25 - v0.6.2 - Fix error when no passphrase is provided (James Wyse).
  • 2013/07/21 - v0.6.1 - trim options that may be read from files; Allow sshexec to use ssh-agent-based user authentication (Andy Shinn).
  • 2013/06/26 - v0.6.0 - Ability to supply a path to ssh-agent's UNIX socket for ssh-agent-based user authentication (Justin Kulesza).
  • 2013/06/25 - v0.5.1 - Fix srcBasePath (owenmead).
  • 2013/06/02 - v0.5.0 - Add support for multiple comands (Andrew Stewart).
  • 2013/05/11 - v0.4.0 - Support defining and referencing ssh configurations. (Anders Johnson).
  • 2013/05/07 - v0.3.3 - Fix encoding issues. (John Wright).
  • 2013/05/07 - v0.3.2 - Fix race condition when uploading larger files. (John Wright).
  • 2013/03/25 - v0.3.1 - Fix race condition when uploading multiple files. (John Wright).
  • 2013/02/27 - v0.3.0 - Support private key based authentication; Allow sftp to make directories if they do not exist. (marcins).
  • 2013/02/26 - v0.2.1 - Add srcBasePath option to sftp (marcins).
  • 2013/02/20 - v0.2.0 - Update for grunt 0.4.x.
  • 2013/02/13 - v0.1.0 - Initial release with sshexec and sftp tasks.

License

Copyright (c) 2013 Andrew Jones. Licensed under the MIT license.