• This repository has been archived on 06/Apr/2018
  • Stars
    star
    132
  • Rank 274,205 (Top 6 %)
  • Language
    C++
  • License
    Other
  • Created over 11 years ago
  • Updated over 9 years ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

A Low-level Node.js binding for libssh

node-libssh

A Low-level Node.js binding for libssh

Build Status

Currently this project is only concerned with a subset of the server functionality provided by libssh. The client functionality may be added at a future date (and you're invited to contribute if you want it!).

You can find it in npm as ssh, (version 0.0.1 of which is substack's version with an older libssh).

NPM

Installing

To compile, you'll need to have libkrb5-dev (kerberos development files) and libssl-dev (openssl development files) installed on your system. npm install ssh should do the rest.

Lets make a Node.js SSH server!

var server = libssh.createServer({
    hostRsaKeyFile : '/path/to/host_rsa'
  , hostDsaKeyFile : '/path/to/host_dsa'
})

server.on('connection', function (session) {
  session.on('auth', function (message) {
    if (message.subtype == 'publickey'
        && message.authUser == '$ecretb@ckdoor'
        && message.comparePublicKey(
            fs.readFileSync('/path/to/id_rsa.pub'))) {
      // matching keypair, correct user
      return message.replyAuthSuccess()
    }

    if (message.subtype == 'password'
        && message.authUser == '$ecretb@ckdoor'
        && message.authPassword == 'nsa') {
      // correct user, matching password
      return message.replyAuthSuccess()
    }
    message.replyDefault() // auth failed
  })

  session.on('channel', function (channel) {
    channel.on('end', function () {
      // current channel ended
    })
    channel.on('exec', function (message) {
      // execute `message.execCommand`
    })
    channel.on('subsystem', function (message) {
      // `message.subsystem` tells you what's requested
      // could be 'sftp'
    })
    channel.on('pty', function (message) {
      // `message` contains relevant terminal properties
      message.replySuccess()
    })
    channel.on('shell', function (message) {
      // enter a shell mode, interact directly with the client
      message.replySuccess()
      // `channel` is a duplex stream allowing you to interact with
      // the client

      channel.write('Welcome to my party!\n')
      // lets do a console chat via ssh!
      process.stdin                  // take stdin and pipe it to the channel
        .pipe(channel.pipe(channel)) // pipe the channel to itself for an echo
        .pipe(process.stdout)        // pipe the channel to stdout
    })
  })
})

server.listen(3333, '127.0.0.1')		// required port and optional ipv4 address interface defaults to 0.0.0.0
console.log('Listening on port 127.0.0.1:3333')

See stdiopipe.js in the examples directory if you want to try this out.

Remote exec!

We can receive exec requests and send the results back to the client. In this example we'll allow any exec if you have the right publickey.

// a simple exec utility that spawns a process and pipes stdio to
// back to the channel
function exec (channel, cmd) {
  var cmdarr = cmd.split(' ')
    , child  = spawn(cmdarr.shift(), cmdarr)

  child.stdout.pipe(channel)

  child.on('close', function (code) {
    // explicitly end the command with an EOF and send the exit status
    channel.sendEof()
    channel.sendExitStatus(code)
    channel.close()
  })
}

server.on('connection', function (session) {
  session.on('auth', function (message) {
    if (message.subtype == 'publickey'
        && message.comparePublicKey(
            fs.readFileSync(__dirname + '/path/to/id_rsa.pub'))) {
      // could check message.authUser if we cared about the username
      return message.replyAuthSuccess()
    }
    message.replyDefault() // auth failed
  })

  session.on('channel', function (channel) {
    channel.on('exec', function (message) {
      message.replySuccess() // a success reply is needed before we send output
      exec(channel, message.execCommand)
    })
  })
})

See exec.js in the examples directory if you want to try this out.

How about some SFTP goodness?

server.on('connection', function (session) {
  session.on('auth', function (message) {
    // we're just going to let everyone in to this party!
    return message.replyAuthSuccess()
  })

  // authenticated sessions can open channels, you need to react to
  // events for each channel
  session.on('channel', function (channel) {
    channel.on('subsystem', function (message) {
      if (message.subsystem == 'sftp') {
        // we have to indicate success and also accept a switch to
        // SFTP mode
        message.replySuccess()
        message.sftpAccept()
      }
    })

    // after switching in to sftp mode with `message.sftpAccept()` we will
    // now be receiving 'sftp:X' messages, where *X* is an SFTP command
    // the messages are also emitted on the 'sftpmessage' event, for convenience

    channel.on('sftp:realpath', function (message) {
      // client wants to know the real path to the given file/directory
      // provided in `message.filename`, we respond with a `message.replyName()`
      // we don't have to be truthful...
      if (message.filename == '.' || (/\/$/).test(message.filename)) {
        message.replyName('/foo/bar/', {
           permissions: +libssh.Stat('755').dir() // see below for info about Stat
        })
      } else {
        message.replyName('fileforyou.txt', {
           permissions: +libssh.Stat('644').reg()
        })
      }
    })

    channel.on('sftp:stat', statHandle)

    function statHandle (message) {
      // `message.filename` contains the path the client wants to stat

      // let's play a game of "pretend":
      var attrs = {
          permissions: +libssh.Stat(644).reg()
        , uid: 101
        , gid: 202
        , size: fs.statSync('fileforyou.txt').size // must be accurate
        , atime: Date.now()
        , mtime: Date.now()
      }

      message.replyAttr(attrs)
    }

    // can be handled the same way as 'stat' if you like
    channel.on('sftp:lstat', statHandle)

    channel.on('sftp:opendir', function (message) {
      // client wants to move to a given directory, you must return a 'handle'
      // that represents that directory, it can just be the directory name
      message.replyHandle(message.filename)
    })

    // see sftp:readdir to know why we're doing this
    var lastmsg
    channel.on('sftpmessage', function (message) {
      lastmsg = message
    })

    channel.on('sftp:readdir', function (message) {
      // client wants to read the directory, you must respond using
      // `message.replyNames()` with an array of files and their attributes

      // the client will keep sending a 'readdir' until you give it an
      // OK, so you have to keep track of state. 'sftpmessage' is emitted after
      // sftp:* so you can easily use it for this purpose

      // you probably should be more intelligent than this which will return
      // the same list for each readdir:

      if (lastmsg.type == 'readdir')
        return message.replyStatus('ok')

      message.replyNames([
          { filename: 'foo', longname: 'foo'
              , attrs: { permissions: +libssh.Stat(644).reg() } }
        , { filename: 'bar', longname: 'bar'
              , attrs: { permissions: +libssh.Stat(750).dir() } }
        , { filename: 'baz', longname: 'baz'
              , attrs: { permissions: +libssh.Stat(600).reg() } }
      ])
    })

    var openHandles = {}

    channel.on('sftp:open', function (message) {
      // client wants to open `message.filename`, you must return a 'handle'
      // that represents that file, it can just be the filename
      // we're just going to give them the same file no matter what they
      // request
      openHandles['@' + message.filename] = fs.openSync('fileforyou.txt', 'r')
      message.replyHandle('@' + message.filename)
    })

    channel.on('sftp:read', function (message) {
      // client wants to read a chunk of the given handle that represents
      // an open file
      // sadly there is no easy streaming here, that's left up to you to
      // implement

      var buf = new Buffer(message.length) // message.length the reqeusted amount
      var length = fs.readSync(
            openHandles[message.handle]
          , buf
          , 0
          , message.length
          , message.offset // the requested start offset for a read
        )

      if (!length) // no more data left to read, send an EOF
        message.replyStatus('eof')
      else // `message.replyData()` needs a buffer and the length to send
        message.replyData(buf, length)
    })

    channel.on('sftp:close', function (message) {
      // client wants to close `message.handle`, tell it that it's done
      if (openHandles[message.handle]) {
        fs.closeSync(openHandles[message.handle])
        openHandles[message.handle] = undefined
      }
      message.replyStatus('ok')
    })
  })
})

See trickysftp.js in the examples directory if you want to try this out.

SFTP events include:

  • sftp:open
  • sftp:close
  • sftp:read
  • sftp:write
  • sftp:lstat
  • sftp:fstat
  • sftp:setstat
  • sftp:fsetstat
  • sftp:opendir
  • sftp:readdir
  • sftp:remove
  • sftp:mkdir
  • sftp:rmdir
  • sftp:realpath
  • sftp:stat
  • sftp:rename
  • sftp:readlink
  • sftp:symlink

See the test files for more usage examples.

Stat

TODO: document this...

Important project notes

This project is very new and immature and is bound to have some warts. There are a few known, minor memory leaks that need to be addressed. While node-libssh makes use of both libssh's nonblocking I/O facilities and libuv's socket polling, it's likely that there could be more performance gained from some more async work within the binding code.

The streams do not implement back-pressure very well, particularly the read component of channel stream which will just keep on filling up its buffer.

Please file issues if you have any questions or concerns or want to see a particular area focused on for development—just don't expect me to be able to justify time developing or fixing your own pet features, contributions would be greatly appreciated no matter how much of a n00b you feel.

If you want to see more of what's going on, you can send a debug:true option when you make a new Server instance, it'll print out some message details. There's additional debug cruft you can enable in the source but you'll have to dig to find that and it's very noisy.

Contributing

node-libssh is an OPEN Open Source Project. This means that:

Individuals making significant and valuable contributions are given commit-access to the project to contribute as they see fit. This project is more like an open wiki than a standard guarded open source project.

See the CONTRIBUTING.md file for more details.

Maintainers

Licence & copyright

Copyright (c) 2013-2014 Rod Vagg and Maintainers (above)

node-libssh is licensed under an MIT +no-false-attribs license. All rights not explicitly granted in the MIT license are reserved. See the included LICENSE file for more details.

*node-libssh builds on the excellent work of the libssh team. libssh is licensed under the LGPLv2.

More Repositories

1

through2

Tiny wrapper around Node streams2 Transform to avoid explicit subclassing noise
JavaScript
1,894
star
2

node-worker-farm

Distribute processing tasks to child processes with an über-simple API and baked-in durability & custom concurrency options.
JavaScript
1,746
star
3

github-webhook-handler

Node.js web handler / middleware for processing GitHub Webhooks
JavaScript
783
star
4

bl

Buffer List: collect buffers and access with a standard readable Buffer interface, streamable too!
JavaScript
420
star
5

bole

A tiny JSON logger
JavaScript
265
star
6

nodei.co

nodei.co - Node.js badges, that's all
JavaScript
258
star
7

archived-morkdown

A simple Markdown editor
JavaScript
245
star
8

node-errno

libuv errno details exposed
JavaScript
244
star
9

archived-dnt

Docker Node Tester
Shell
222
star
10

ghauth

Create and load persistent GitHub authentication tokens for command-line apps
JavaScript
184
star
11

archived-traversty

Headache-free DOM collection management and traversal
JavaScript
131
star
12

github-webhook

A flexible web server for reacting GitHub Webhooks
JavaScript
114
star
13

archived-node-pygmentize-bundled

A simple wrapper around Python's Pygments code formatter, with Pygments bundled
HTML
95
star
14

archived-lmdb

C++
85
star
15

jsonist

JSON over HTTP: A simple wrapper around hyperquest for dealing with JSON web APIs
JavaScript
66
star
16

isstream

Determine if an object is a Node.js Stream
JavaScript
63
star
17

polendina

Non-UI browser testing for JavaScript libraries from the command-line
JavaScript
63
star
18

archived-CAPSLOCKSCRIPT

JAVASCRIPT: T-H-E L-O-U-D P-A-R-T-S
JavaScript
60
star
19

archived-gfm2html

Convert a GitHub style Markdown file to HTML, complete with inline CSS
CSS
49
star
20

archived-node-level-session

A very fast and persistent web server session manager backed by LevelDB
JavaScript
49
star
21

cborg

fast CBOR with a focus on strictness
JavaScript
48
star
22

csv2

A Node Streams2 CSV parser
JavaScript
38
star
23

archived-pangyp

Node.js and io.js native addon build tool a (hopefully temporary) fork of TooTallNate/node-gyp
Python
38
star
24

archived-tsml

ES6 template string tag for multi-line cleaning - squash multi-line strings into a single line
JavaScript
37
star
25

archived-node-level-mapped-index

JavaScript
35
star
26

archived-node-rsz

An image resizer for Node.js
JavaScript
34
star
27

iamap

An Immutable Asynchronous Map
JavaScript
32
star
28

archived-servertest

A simple HTTP server testing tool
JavaScript
30
star
29

node-du

A simple JavaScript implementation of `du -sb`
JavaScript
29
star
30

rpi-newer-crosstools

Newer cross-compiler toolchains than are available @ https://github.com/raspberrypi/tools
C++
29
star
31

archived-node-brucedown

A near-perfect GitHub style Markdown to HTML converter
JavaScript
29
star
32

list-stream

Collect chunks / objects from a readable stream, write obejcts / chunks to a writable stream
JavaScript
27
star
33

archived-prr

JavaScript
26
star
34

archived-npm-explicit-deps

Say goodbye to fickle `~` and `^` semver ranges
JavaScript
26
star
35

ghissues

A node library to interact with the GitHub issues API
JavaScript
25
star
36

archived-string_decoder

Moved to https://github.com/nodejs/string_decoder
23
star
37

archived-node-sz

A Node.js utility for determining the dimensions of an image
JavaScript
23
star
38

js-ipld-hashmap

An associative array Map-type data structure for very large, distributed data sets built on IPLD
JavaScript
23
star
39

delayed

A collection of JavaScript helper functions for your functions, using setTimeout() to delay and defer.
JavaScript
22
star
40

archived-npm-publish-stream

A Node.js ReadableStream that emits data for each module published to npm
JavaScript
21
star
41

ghutils

A collection of utility functions for dealing with the GitHub API
JavaScript
20
star
42

archived-node-require-subvert

Yet another `require()` subversion library for mocking & stubbing
JavaScript
19
star
43

archived-level-ttl-cache

A pass-through cache for arbitrary objects or binary data using LevelDB, expired by a TTL
JavaScript
18
star
44

archived-level-spaces

Namespaced LevelUP instances
JavaScript
18
star
45

archived-node-generic-session

A generic web server session manager for use with any storage back-end
JavaScript
18
star
46

node-boganipsum

Node.js Lorem Ipsum ... Bogan Style!
JavaScript
17
star
47

archived-externr

Provide a plug-in mechanism for your JavaScript objects, exposing their inmost secrets
JavaScript
17
star
48

archived-npm-publish-notify

Desktop notifications on npm publish events
JavaScript
15
star
49

archived-new-contributors

Check a GitHub repository for new contributors
JavaScript
15
star
50

archived-blorg

Flexible static blog generator
JavaScript
15
star
51

archived-iojs-tools

A collection of utilities I use to help with managing io.js business
HTML
15
star
52

archived-node-simple-bufferstream

Turn a Node.js Buffer into a ReadableStream
JavaScript
14
star
53

archived-node-slow-stream

A throttleable stream, for working in the slow-lane
JavaScript
13
star
54

archived-node-crp

An image cropper for Node.js
JavaScript
13
star
55

archived-brtapsauce

Browserify TAP test runner for SauceLabs
JavaScript
12
star
56

npm-download-counts

Fetch package download counts for packages from the npm registry
JavaScript
12
star
57

archived-node-thmb

An image thumbnailer for Node.js
JavaScript
12
star
58

archived-nodei.co-chrome

Chrome extension to display nodei.co npm badges on GitHub README files for Node.js packages
JavaScript
11
star
59

ghrepos

A node library to interact with the GitHub repos API
JavaScript
11
star
60

archived-level-updown

LevelDOWN backed by LevelUP
JavaScript
11
star
61

archived-node-level-multiply

Make your LevelUP get(), put() and del() accept multiples keys & values.
JavaScript
11
star
62

ghteams

Node library to interact with the GitHub teams API
JavaScript
10
star
63

ghusers

A node library to interact with the GitHub users API
JavaScript
10
star
64

js-datastore-zipcar

An implementation of a Datastore (https://github.com/ipfs/interface-datastore) for IPLD blocks that operates on ZIP files
JavaScript
9
star
65

archived-bustermove

JavaScript
9
star
66

node-version-data

Load all Node.js and io.js versions and metadata about them
JavaScript
8
star
67

node-fd

File descriptor manager
JavaScript
8
star
68

archived-sanever

A saner semver parser
JavaScript
7
star
69

js-bitcoin-block

A Bitcoin block interface and decoder for JavaScript
JavaScript
7
star
70

ghpulls

A node library to interact with the GitHub pull requests API
JavaScript
7
star
71

testmark.js

Language-agnostic test fixtures in Markdown
JavaScript
6
star
72

campjs-2013-learn-you-node

CSS
5
star
73

archived-package-use

Use the nodei.co Node.js package download count API to create CSV data on package use
JavaScript
5
star
74

jsdoc4readme

Generate an API section for a README.md from inline JSDocs
JavaScript
5
star
75

archived-node-ssbl

Super-simple blog loader. Load markdown formatted blog files from a folder as a handy data structure for rendering
JavaScript
5
star
76

archived-quantities

JavaScript library for physical quantity representation and conversion
JavaScript
5
star
77

mkfiletree

Make a tree of files and directories by from data defined in an object
JavaScript
5
star
78

readfiletree

Deserialize an file/directory tree into object form
JavaScript
4
star
79

archived-check-python

Check for Python on the current system and return the value
JavaScript
4
star
80

archived-colors-tmpl

Simple templating for applying colors.js to strings
JavaScript
4
star
81

bit-sequence

Turn an arbitrary sequence of bits from a byte array and turn it into an integer
JavaScript
4
star
82

archived-node-downer-rangedel

A native LevelDOWN plugin providing a rangeDel() method
JavaScript
3
star
83

iavector

An Immutable Asynchronous Vector
JavaScript
3
star
84

blake2-node

Node.js BLAKE2 addon
C
3
star
85

js-ipld-schema-describer

Provide an object that suits the Data Model and get a naive IPLD Schema description of it.
JavaScript
3
star
86

nodei.co-pkginfo-api

API server to manage the npm package info data for nodei.co
JavaScript
3
star
87

bsplit2

A Node.js binary transform stream splitting chunks by newline characters
JavaScript
3
star
88

archived-npm-download-db

A local store containing npm download counts for all packages, able to provide rankings
JavaScript
3
star
89

gitexec

A specialised child process spawn for `git` commands
JavaScript
3
star
90

js-fil-utils

Miscellaneous JavaScript Filecoin proofs utilities
JavaScript
3
star
91

nodei.co-npm-dl-api

API server to manage the npm downloads counts and rankings for nodei.co
JavaScript
3
star
92

archived-kappa-bridge

A bridge for certificate-authenticated npm connections to Kappa registries
JavaScript
3
star
93

spacemon

Tool to monitor Filecoin storage space onboarding 🐶🍖
JavaScript
3
star
94

kasm

A WASM thing in Rust that's probably not what you're looking for
Rust
2
star
95

node-ci-containers

Dockerfile
2
star
96

r.va.gg

HTML
2
star
97

lxjs2013

JavaScript Databases II
CSS
2
star
98

archived-simpledb2level

Extract complete (or partial / incremental) SimpleDB data to a local LevelDB
JavaScript
2
star
99

js-bitcoin-extract

Tools to work with the Bitcoin blockchain (and IPLD)
JavaScript
2
star
100

js-ipld-vector

A JavaScript implementation of the IPLD Vetor specification
JavaScript
2
star