@episensor/node-red-contrib-epi-ssh

EpiSensor Node-RED nodes for SSH/SFTP file transfer - upload and download files via SSH.

Install

Run the following command in your Node-RED user directory (typically ~/.node-red):

npm install @episensor/node-red-contrib-epi-ssh

Features

• Download files from remote servers via SFTP
• Upload files to remote servers via SFTP
• Password authentication support
• Private key authentication support (with optional passphrase)
• Buffer or file output modes for downloads
• Automatic directory creation for uploads
• Detailed error reporting with error forwarding to output
• Support for all standard SSH configurations

Prerequisites

• Node.js 14 or later
• Node-RED 3.0 or later
• SSH access to remote server(s)

Nodes

SFTP Download (epi-ssh-download)

Downloads files from a remote server via SSH/SFTP.

Input

• msg.remotePath (string): Override the configured remote file path
• msg.localPath (string): Override the configured local path (for file output mode)
• msg.outputMode (string): Override output mode ("buffer" or "file")

Output

Buffer mode (default):

• msg.payload (Buffer): The downloaded file content

File mode:

• msg.payload (object): Contains success, remotePath, localPath, and size

Both modes:

• msg.remotePath (string): The remote path that was downloaded
• msg.fileSize (number): Size of the file in bytes
• msg.error (Error, optional): Error details if download fails

Example

// Download to buffer
msg.remotePath = "/home/user/data.csv";
return msg;

// Download to local file
msg.remotePath = "/home/user/data.csv";
msg.localPath = "/tmp/data.csv";
msg.outputMode = "file";
return msg;

SFTP Upload (epi-ssh-upload)

Uploads files to a remote server via SSH/SFTP.

Input

• msg.payload (Buffer | string | object): The content to upload
  • Buffers are uploaded directly
  • Strings are converted to UTF-8
  • Objects are JSON-stringified
• msg.remotePath (string): Override the configured remote destination path
• msg.localPath (string): Path to a local file to upload (alternative to payload)
• msg.createDirs (boolean): Override whether to create remote directories

Output

• msg.payload (object): Contains success, remotePath, size, and optionally localPath
• msg.remotePath (string): The remote path where the file was uploaded
• msg.error (Error, optional): Error details if upload fails

Example

// Upload string content
msg.remotePath = "/home/user/output.txt";
msg.payload = "Hello, SSH!";
return msg;

// Upload JSON object
msg.remotePath = "/home/user/config.json";
msg.payload = { setting: "value", count: 42 };
return msg;

// Upload from local file
msg.remotePath = "/home/user/backup.zip";
msg.localPath = "/local/path/to/file.zip";
return msg;

Configuration

SSH Config Node

Create an SSH configuration node with your server credentials:

1. Host: The hostname or IP address of the SSH server
2. Port: SSH port (default: 22)
3. Username: SSH username

Authentication (choose one):

• Password: SSH password
• Private Key Path: Path to your private key file (e.g., ~/.ssh/id_rsa)
• Passphrase: Passphrase for encrypted private keys

Authentication Examples

Password authentication:

Host: 192.168.1.100
Port: 22
Username: deploy
Password: ********

Private key authentication:

Host: server.example.com
Port: 22
Username: deploy
Private Key: /home/nodered/.ssh/id_rsa
Passphrase: ******** (if key is encrypted)

Status Indicators

• Blue dot: Connecting or transferring
• Red dot: Error occurred
• Red ring: Missing or invalid configuration
• No status: Ready/completed successfully

Error Handling

Both nodes send error messages to their output, allowing downstream nodes to handle errors:

• msg.error contains the error object
• msg.payload is set to null on error
• Errors are also logged via node.error()

Common error scenarios:

• Host not found
• Connection refused
• Connection timeout
• Authentication failed
• File not found
• Permission denied
• File too large (>500MB)

Limitations

• Maximum file size: 500MB
• Single file operations only (no batch/recursive operations)
• Connection timeout: 30 seconds

Security Notes

• Credentials are stored securely using Node-RED's built-in credential encryption
• Private key files should have appropriate permissions (600)
• Consider using dedicated service accounts with minimal required permissions
• Avoid storing passwords in flows - use the configuration node

Testing

# Run unit tests
npm test

# Run tests with coverage
npm run test:coverage

# Run tests in watch mode
npm run test:watch

Development

Prerequisites

• Node.js 14 or later
• Node-RED 3.0 or later for testing

Setup

1. Clone the repository
2. Install dependencies: npm install
3. Run tests: npm test

Contributing

1. Fork the repository
2. Create your feature branch: git checkout -b feature/my-new-feature
3. Commit your changes: git commit -am 'Add some feature'
4. Push to the branch: git push origin feature/my-new-feature
5. Submit a pull request

Support

For issues and feature requests, please use the GitHub issue tracker.

License

Licensed under the Apache License, Version 2.0. See LICENSE for details.

Version History

• 0.1.0 (2024-12)
  • Initial release
  • SFTP download node with buffer and file output modes
  • SFTP upload node with payload and local file support
  • SSH configuration node with password and private key authentication
  • Automatic remote directory creation for uploads
  • Comprehensive error handling