zenci-shell
Wrapper class for Node.js ssh2 shell command for running multiple commands
This package was originaly based on https://github.com/cmp-202/ssh2shell. Please check it first, maybe you do not need extra features provided by zenci-shell.
Since v0.2 it was completely rewrited and has different functionality now. This class enables the following functionality:
- Run multiple commands sequentially.
- Callback with object that contain command name, status and output. Ability to add new command to command list based on output.
- Time tracking per each command.
- Status from command.
- Respond contain only command output.
Installation:
npm install zenci-shell
Requirements:
The class expects an object with the following structure to be passed to its constructor:
//Host objecthost = server: host: "IP Address" port: "external port number" userName: "user name" password: "user password" passPhrase: "privateKeyPassphrase" //optional string privateKey: //optional string keep_alive: false //optional string. Do not close SSH connection and wait for new commands to run. commands: "Array" "of" "strings" "command" //array() of command strings. IF keep_alive is true, this is optional. idleTimeOut: 5000 //optional number in milliseconds idleCommandTime: 100 //optional how often check for new commands in queue;
Minimal Example:
/** * Simple list example. * see file example/simple.js */"use strict";var ZENCIShell = ; var host = server: host: "localhost" userName: "test" password: 'test' commands: "echo $(pwd)" "echo test" ; // Create a new instance.var SSH = host; // Get command output when finishedSSH; // Start the process.SSH;
Usage:
Connecting to a single host:
How to:
- Use an .env file for server values loaded by dotenv from the root of the project.
- Connect using a key pair with passphrase.
- Set commands.
- Test the response of a command and add more commands and notifications in the host.onCommandComplete event handler.
- Use the two notification types in the commands array.
.env
HOST=192.168.0.1
PORT=22
USER_NAME=myuser
PASSWORD=mypassword
PRIV_KEY_PATH=~/.ssh/id_rsa
PASS_PHRASE=myPassPhrase
app.js
var dotenv = ;dotenv;var ZENCIShell = ; var host = server: host: processenvHOST port: processenvPORT userName: processenvUSER_NAME password: processenvPASSWORD passPhrase: processenvPASS_PHRASE privateKey: commands: "echo $(pwd)" "cd ~/" "ls -l" "echo $(pwd)" "ls -l" ; // Create a new instance.var SSH = host; // Get command output when finishedSSH; // Start the process.SSH; SSH
Trouble shooting:
- Recheck your passphrase for typos or missing chars.
- Try connecting manually to the host using the exact passhrase used by the code to confirm it works.
- If your password is incorrect the connection will return an error.
- There is an optional debug setting via ENV vars. in the host object that will output progress information when set to true and passwords for failed authentication of sudo commands and tunnelling.
DEBUG=ssh:* node example/simple.js
- The class now has an idle time out timer (default:5000ms) to stop unexpected command prompts from causing the process hang without error. The default time out can be changed by setting the host.idleTimeOut with a value in milliseconds. (1000 = 1 sec)
Authentication:
- When using key authentication you may require a valid passphrase if your key was created with one.
Verbose and Debug:
DEBUG=ssh:* node example/simple.js
There is 3 levels of debug info:
- ssh:events - print events that happening inside package. Like connected, ready, command sent etc
- ssh:raw - pring raw respond from server
- ssh:*-print events and raw respond from server
Event Handlers:
By using SSH.exec(command, function (notice) { // some action. })
You can specify custom callback to handle next action based on output. All commands are running in sequential mode. So you can call SSH.exec without waiting for respond if needed.
Further reading: node.js event emitter
Class Instance Event Definitions:
zenci-shell; zenci-shell; zenci-shell; zenci-shell; zenci-shell; zenci-shell; zenci-shell;
Check example directory for example usage.