1 | # nodemiral (node + admiral) [![Build Status](https://travis-ci.org/arunoda/nodemiral.png?branch=master)](https://travis-ci.org/arunoda/nodemiral)
|
2 | ### Server Automation for NodeJS over SSH
|
3 |
|
4 | ## Install
|
5 | ~~~js
|
6 | npm install nodemiral
|
7 | ~~~
|
8 |
|
9 | ## Features
|
10 |
|
11 | * Support connecting to any unix remote server
|
12 | * Authenticate with password(using [`sshpass`](http://sourceforge.net/projects/sshpass/)) or with a `pem` file
|
13 | * Can work with multiple servers at once
|
14 | * Supports, `copy`, `execute` and `executeScript` at core methods
|
15 | * Familiar NodeJS API
|
16 |
|
17 | ## Example
|
18 | ~~~js
|
19 | var nodemiral = require('nodemiral');
|
20 | var session = nodemiral.session('hostname', {username: 'root', password: 'password'});
|
21 |
|
22 | session.execute('uname -a', function(err, code, logs) {
|
23 | console.log(logs.stdout);
|
24 | });
|
25 | ~~~
|
26 |
|
27 | ## API
|
28 |
|
29 | ### Session
|
30 |
|
31 | Create a session to a remote server. You can invoke following methods after created a session
|
32 |
|
33 | @param hostname - hostname or ip addess
|
34 | @param auth - object containing following fields: `username` and (`password` or `pem`)
|
35 | @param options - object of options described below
|
36 | nodemiral.session(hostname, auth, options);
|
37 |
|
38 | `options`:
|
39 |
|
40 | * `ejs` - ejs options with `ejs` fields
|
41 | * `ssh` - object whose key and value will be passed as `-o key:value` to any ssh session. For example `{ 'StrictHostKeyChecking': 'no', 'UserKnownHostsFile': '/dev/null' }`
|
42 |
|
43 | ### Session Methods
|
44 |
|
45 | #### execute
|
46 | execute given shell command on the remote server
|
47 |
|
48 | @param shellCommand - shellCommand
|
49 | @param options - {onStdout, onStderr}
|
50 | @param callback - callback containing following parameters
|
51 | err - err if exists
|
52 | code - status code of the ssh process
|
53 | logs - {stdout: 'stdout logs', stderr: 'stderr logs'}
|
54 | session.execute(shellCommand, callback);
|
55 |
|
56 | #### executeScript
|
57 | execute a local shell script in the remote server. You can template shell script with [EJS](https://github.com/visionmedia/ejs).
|
58 |
|
59 | @param localScriptFile - localScriptFile
|
60 | @param options.vars - variables to the template if uses ejs in the script
|
61 | @param callback - callback containing following parameters
|
62 | err - err if exists
|
63 | code - status code of the ssh process
|
64 | logs - {stdout: 'stdout logs', stderr: 'stderr logs'}
|
65 | session.executeScript(localScriptFile, options, callback);
|
66 |
|
67 | #### copy
|
68 | copy a file from local machine to the remote machine. Supports binary files too. Support EJS templating with non-binary files
|
69 |
|
70 | @param localFile - localFile
|
71 | @param remoteFileLocation - remoteFileLocation
|
72 | @param options.vars - templateVars
|
73 | @param optiosn.progressBar - show progress bar
|
74 | @param callback - callback containing following parameters
|
75 | err - err if exists
|
76 | code - status code of the ssh process
|
77 | logs - {stdout: 'stdout logs', stderr: 'stderr logs'}
|
78 | session.copy(localFile, remoteFileLocation, options, callback)
|