1670560320
3 Ways to Connect and SSH into an EC2 Instance – AWS. In this guide you are going to learn how to connect to your EC2 instance from your local Linux or Mac or from your Windows machine.
Before you connect to your EC2 instance make sure your IP address is added in the Firewall to allow connections from your IP address or your instance allows connection from anywhere.
This is the easiest way to connect yo your Instance instantly. This method don’t require any additional clients installed in your local machine. To use this method,
Select your Instance and click the Connect button in your EC2 Dashboard.
In the Connection method choose EC2 Instance Connect.
The username of the AMI will get populated automatically.
Now click Connect.
Now a new window will get opened and a connection will get established to your Instance.
If you get any errors you need to wait for sometime once your instance is created.
From your Linux/Mac machine you can simply open your terminal window, use the ssh command to connect to the instance. You specify the private key (.pem) file, the user name for your AMI (in this case it is ubuntu), and the public DNS name for your instance or your Elastic IP address.
The connection string looks similar to the one below.
ssh -i "cloudbooklet.pem" ubuntu@ec2-35-171-69-92.compute-1.amazonaws.com
To SSH to your instance you need to convert your private key (.pem) file using PUTTYgen to ppk format.
Open PUTTYgen and Click Load.
Select the pem key you have downloaded while created your instance.
Once the file is imported, click Save private key to convert it to ppk format.
Save the file.
Launch PUTTY.
In Hostname/IP address enter DNS name or Elastic IP address.
In Port enter default 22.
In the left menu under Connection expand SSH and click Auth.
Browse and select the PPK file you just converted using PUTTYgen.
Now click Open.
This will create an SSH connection to your EC2 Instance.
Become a Certified AWS Professional with this easy to learn course now.
Now you have learned how to connect to your EC2 instance in AWS using standalone method or browser connection..
Thanks for your time. If you face any problem or any feedback, please leave a comment below.
Original article source at: https://www.cloudbooklet.com/
1670518920
A comprehensive tutorial on how to log SSH activity—minus sensitive input, like passwords—occurring in Linux AWS EC2 instances to either CloudWatch Logs or S3 buckets.
Setting up custom tools or scripts to keep an SSH log on Linux can be tedious and error-prone.
Engineers can use rootsh, screen, or another utility to log user activity but if the user permissions are not set correctly, a skilled user can erase audit logs to cover their tracks. Another option would be to set up logging at the kernel level, but the expertise needed for that isn’t so common.
Thankfully, there’s a way to log user activity without writing even a single Linux command! We’ll need these services:
Let’s see how to set up each of them.
Launching an EC2 instance is normally fairly easy, but there’s one key task that must be done during launch: We need to attach an IAM role to our instance, otherwise we won’t be able to achieve the expected results detailed at the end of this article.
The IAM role we associate with our EC2 instance must have the built-in AmazonSSMManagedInstanceCore policy, plus this policy (attached as inline or customer-managed):
{
"Version": "2012-10-17",
"Statement": [
{
"Action": [
"logs:CreateLogStream",
"logs:DescribeLogStreams",
"logs:DescribeLogGroups",
"logs:PutLogEvents"
],
"Effect": "Allow",
"Resource": "*"
}
]
}
Aside from the IAM role, we generally use this EC2 instance configuration:
We can start to set up KMS without waiting for the EC2 instance to boot up.
We need a KMS key if we want all session logs delivered to CloudWatch to be stored encrypted. Let’s head over to the KMS service and create a key.
Step 1: Choosing a symmetric key type.
Step 2: Naming our key.
Step 3 (optional): Assigning an administrator.
We recommend assigning an administrator so that the key can be managed by users other than the AWS account root user, but if others won’t need access, we can skip Step 3.
Here we chose the IAM user “admin” as a key administrator, but we’re free to choose any user or role. We can also opt to disable key deletion permission for the administrator.
Step 4: Skipping the user assignment page.
We won’t be assigning any users to this key because we want this key to be used only by the CloudWatch Logs service for SSH log encryption and decryption operations.
Step 5: Review our configuration and swap the default key policy.
On the Review page, we will need to change the KMS-generated key policy because it doesn’t include permissions for CloudWatch Logs to use the key. We’ll replace it with this policy:
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "Enable IAM User Permissions",
"Effect": "Allow",
"Principal": {
"AWS": "arn:aws:iam::ACCOUNT_ID:root"
},
"Action": "kms:*",
"Resource": "*"
},
{
"Sid": "Allow access for Key Administrators",
"Effect": "Allow",
"Principal": {
"AWS": "arn:aws:iam::ACCOUNT_ID:user/USERNAME"
},
"Action": [
"kms:Create*",
"kms:Describe*",
"kms:Enable*",
"kms:List*",
"kms:Put*",
"kms:Update*",
"kms:Revoke*",
"kms:Disable*",
"kms:Get*",
"kms:Delete*",
"kms:TagResource",
"kms:UntagResource",
"kms:ScheduleKeyDeletion",
"kms:CancelKeyDeletion"
],
"Resource": "*"
},
{
"Sid": "Allow access to CloudWatch Log",
"Effect": "Allow",
"Principal": {
"Service": "logs.REGION.amazonaws.com"
},
"Action": [
"kms:Encrypt",
"kms:Decrypt",
"kms:ReEncrypt*",
"kms:GenerateDataKey*",
"kms:DescribeKey"
],
"Resource": "*",
"Condition": {
"ArnLike": {
"kms:EncryptionContext:aws:logs:arn": "arn:aws:logs:REGION:ACCOUNT_ID:*"
}
}
}
]
}
Make sure to replace all the placeholders:
ACCOUNT_ID
becomes our AWS account ID.USERNAME
becomes the administrator username selected in Step 3. If we opted out of that step, here we remove the second statement block (the one with "Sid": "Allow access for Key Administrators"
).REGION
becomes the regional identifier code we are deploying services to (e.g., us-west-1
).With that, KMS is ready to go.
Next we need a CloudWatch Log group (and/or an S3 bucket—see below) where SSM Agent can send SSH session logs. Let’s create it.
Creating a “CloudWatch Logs” log group.
Note the KMS key ARN field: AWS provides us with the value needed here after the key is created in Step 5 of the KMS section.
(If we didn’t associate the correct policy to our KMS key earlier, allowing the CloudWatch Logs service to use the key, we’ll receive an error related to the KMS key at this point.)
For storing activity logs with S3 instead of—or in addition to—CloudWatch Logs, we need to add these permissions to our EC2 instance profile as a separate policy (or manually combine them with other permissions we may need associated):
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"s3:PutObject"
],
"Resource": "arn:aws:s3:::BUCKET_NAME/*"
},
{
"Effect": "Allow",
"Action": [
"s3:GetEncryptionConfiguration"
],
"Resource": "*"
},
{
"Effect": "Allow",
"Action": "kms:GenerateDataKey",
"Resource": "*"
}
]
}
In the above snippet, be sure to replace the BUCKET_NAME
placeholder.
Now that we’ve set up somewhere to store the logs—CloudWatch Logs, an S3 bucket, or both—we’re ready to tap into SSH sessions.
This is the final key step, where we configure secure access to our Linux machine for SSH session monitoring and logging. We’ll start at the Session Manager dashboard.
Step 1: Getting started with the dashboard.
On the dashboard, click on the white “Configure Preferences” button in the upper-right “Start a session” box to enable session logging.
On the Preferences page, we will find multiple sections that we could explore, but our focus will be on streaming SSH session logs to CloudWatch or S3 to allow us to quickly see what is happening within our Linux machine.
Step 2a: Enabling CloudWatch logging.
Just after the “CloudWatch logging” section, there’s an “S3 logging” section where we can select the bucket.
Step 2b: Enabling S3 logging.
Once SSH logging is configured, we can SSH into our Linux machine and execute some commands to see if the activity is getting captured or not.
So, let’s start a session. On the same page, we will find a “Sessions” tab where we can start a session. Clicking the “Start session” button will give us a list of EC2 machines on which we can initiate a session:
Step 3: Selecting our EC2 instance to start an SSH session with.
If we don’t see our EC2 Linux instance in the list, we should check whether it’s in a running state and has the IAM permissions associated with it that we described earlier.
In case we receive an error saying the SSM Agent version installed on our EC2 machine does not support streaming CloudWatch logs, not to worry. There’s a painless way to fix this.
A potential “outdated SSM agent version” error.
To update the SSM Agent, we need to navigate to Run Command in the left panel of the AWS Systems Manager service.
Step 1: Starting with the “Run Command” dashboard.
Once we’re there, we can click on the orange “Run a Command” button, leading to a new page where we can fill in some parameters.
Step 2: Selecting a command document.
We’ll start by selecting AWS-UpdateSSMAgent from the list.
Step 3: Selecting the EC2 instance that has an SSM agent in need of an update.
Once that’s selected, we’ll scroll down until we see the “Targets” section. There we need to select the EC2 instance on which we want to update the SSM Agent, then hit the “Run” button at the end. This will send us to a page where we can monitor the progress of the update.
Step 4: Monitoring our update progress.
The agent update shouldn’t take more than five minutes. Once that’s done, we should be able to create a session back in the Session Manager.
At this point, we should have an SSH session started.
An SSH session using the SSM agent via AWS Systems Manager Session Manager.
After executing a few commands, let’s navigate to the CloudWatch Logs log group (or our S3 bucket, not shown) and confirm that the activity is being recorded.
SSH log events being recorded in CloudWatch Logs.
We now have a setup, with at-rest encryption enabled, recording every command fired in our Linux machine.
In fact, every command may be more than we want: Any secrets provided or generated during the session will be recorded in CloudWatch or S3 and can be seen by anyone who has the required permissions. To prevent that, we can use stty -echo; read passwd; stty echo;
for each secret we need to provide during the session.
Session Manager is a useful tool to gain remote access to our virtual machines in AWS without having to open port 22. In fact, we can’t generate SSH logs this way if we use port forwarding or a direct SSH connection, as the Session Manager documentation notes.
Nonetheless, combining Session Manager with session logging is a robust solution for controlling and monitoring activity within VMs. Moreover, we’re not charged for using the Session Manager service. We only pay for our EC2 instance and CloudWatch Logs or an S3 bucket for storing logs.
For readers who prefer video tutorials, I’ve covered a very similar procedure a bit more thoroughly on YouTube.
Original article source at: https://www.toptal.com/
1667124660
Xterm.js is a front-end component written in TypeScript that lets applications bring fully-featured terminals to their users in the browser. It's used by popular projects such as VS Code, Hyper and Theia.
bash
, vim
, and tmux
, including support for curses-based apps and mouse events.bash
. Xterm.js can be connected to processes like bash
and let you interact with them (provide input, receive output).First, you need to install the module, we ship exclusively through npm, so you need that installed and then add xterm.js as a dependency by running:
npm install xterm
To start using xterm.js on your browser, add the xterm.js
and xterm.css
to the head of your HTML page. Then create a <div id="terminal"></div>
onto which xterm can attach itself. Finally, instantiate the Terminal
object and then call the open
function with the DOM object of the div
.
<!doctype html>
<html>
<head>
<link rel="stylesheet" href="node_modules/xterm/css/xterm.css" />
<script src="node_modules/xterm/lib/xterm.js"></script>
</head>
<body>
<div id="terminal"></div>
<script>
var term = new Terminal();
term.open(document.getElementById('terminal'));
term.write('Hello from \x1B[1;3;31mxterm.js\x1B[0m $ ')
</script>
</body>
</html>
The recommended way to load xterm.js is via the ES6 module syntax:
import { Terminal } from 'xterm';
⚠️ This section describes the new addon format introduced in v3.14.0, see here for the instructions on the old format
Addons are separate modules that extend the Terminal
by building on the xterm.js API. To use an addon, you first need to install it in your project:
npm i -S xterm-addon-web-links
Then import the addon, instantiate it and call Terminal.loadAddon
:
import { Terminal } from 'xterm';
import { WebLinksAddon } from 'xterm-addon-web-links';
const terminal = new Terminal();
// Load WebLinksAddon on terminal, this is all that's needed to get web links
// working in the terminal.
terminal.loadAddon(new WebLinksAddon());
The xterm.js team maintains the following addons, but anyone can build them:
xterm-addon-attach
: Attaches to a server running a process via a websocketxterm-addon-fit
: Fits the terminal to the containing elementxterm-addon-search
: Adds search functionalityxterm-addon-web-links
: Adds web link detection and interactionSince xterm.js is typically implemented as a developer tool, only modern browsers are supported officially. Specifically the latest versions of Chrome, Edge, Firefox, and Safari.
Xterm.js works seamlessly in Electron apps and may even work on earlier versions of the browsers. These are the versions we strive to keep working.
We also publish xterm-headless
which is a stripped down version of xterm.js that runs in Node.js. An example use case for this is to keep track of a terminal's state where the process is running and using the serialize addon so it can get all state restored upon reconnection.
The full API for xterm.js is contained within the TypeScript declaration file, use the branch/tag picker in GitHub (w
) to navigate to the correct version of the API.
Note that some APIs are marked experimental, these are added to enable experimentation with new ideas without committing to support it like a normal semver API. Note that these APIs can change radically between versions, so be sure to read release notes if you plan on using experimental APIs.
Xterm.js follows a monthly release cycle roughly.
All current and past releases are available on this repo's Releases page, you can view the high-level roadmap on the wiki and see what we're working on now by looking through Milestones.
Our CI releases beta builds to npm for every change that goes into master. Install the latest beta build with:
npm install -S xterm@beta
These should generally be stable, but some bugs may slip in. We recommend using the beta build primarily to test out new features and to verify bug fixes.
You can read the guide on the wiki to learn how to contribute and set up xterm.js for development.
Xterm.js is used in several world-class applications to provide great terminal experiences.
<ng-terminal></ng-terminal>
into your component.Do you use xterm.js in your application as well? Please open a Pull Request to include it here. We would love to have it on our list. Note: Please add any new contributions to the end of the list only.
Author: xtermjs
Source Code: https://github.com/xtermjs/xterm.js
License: MIT license
1665761040
MIT-licensed pure-PHP implementations of the following:
SSH-2, SFTP, X.509, an arbitrary-precision integer arithmetic library, Ed25519 / Ed449 / Curve25519 / Curve449, ECDSA / ECDH (with support for 66 curves), RSA (PKCS#1 v2.2 compliant), DSA / DH, DES / 3DES / RC4 / Rijndael / AES / Blowfish / Twofish / Salsa20 / ChaCha20, GCM / Poly1305
\phpseclib3
composer require phpseclib/phpseclib:~3.0
\phpseclib
composer require phpseclib/phpseclib:~2.0
composer require phpseclib/phpseclib:~1.0
To report a security vulnerability, please use the Tidelift security contact. Tidelift will coordinate the fix and disclosure.
Need Support?
Special Thanks to our $50+ sponsors!:
Fork the Project
Ensure you have Composer installed (see Composer Download Instructions)
Install Development Dependencies
composer install
Create a Feature Branch
Run continuous integration checks:
composer global require php:^8.1 squizlabs/php_codesniffer friendsofphp/php-cs-fixer vimeo/psalm
phpcs --standard=build/php_codesniffer.xml
php-cs-fixer fix --config=build/php-cs-fixer.php --diff --dry-run --using-cache=no
psalm --config=build/psalm.xml --no-cache --long-progress --report-show-info=false --output-format=text
vendor/bin/phpunit --verbose --configuration tests/phpunit.xml
Send us a Pull Request
Author: phpseclib
Source Code: https://github.com/phpseclib/phpseclib
License: MIT license
1665114240
Teleport is the easiest, most secure way to access all your infrastructure. Teleport is an identity-aware, multi-protocol access proxy which understands SSH, HTTPS, RDP, Kubernetes API, MySQL, MongoDB and PostgreSQL wire protocols.
On the server-side, Teleport is a single binary which enables convenient secure access to behind-NAT resources such as:
Teleport is trivial to set up as a Linux daemon or in a Kubernetes pod. It's rapidly replacing legacy sshd
-based setups at organizations who need:
In addition to its hallmark features, Teleport is interesting for smaller teams because it facilitates easy adoption of the best infrastructure security practices like:
Teleport is built upon the high-quality Golang SSH implementation. It is fully compatible with OpenSSH, sshd
servers, and ssh
clients.
Project Links | Description |
---|---|
Teleport Website | The official website of the project. |
Documentation | Admin guide, user manual and more. |
Demo Video | 3-minute video overview of Teleport. |
Blog | Our blog where we publish Teleport news. |
Forum | Ask us a setup question, post your tutorial, feedback, or idea on our forum. |
Slack | Need help with your setup? Ping us in our Slack channel. |
Cloud-hosted | We offer Enterprise with a Cloud-hosted option. For teams that require easy and secure access to their computing environments. |
| Follow the Installation Guide
Download the latest binary release, unpack the .tar.gz and run sudo ./install
. This will copy Teleport binaries into /usr/local/bin
.
Then you can run Teleport as a single-node cluster:
sudo teleport start
In a production environment, Teleport must run as root
. For testing or non-production environments, run it as the $USER
:
chown $USER /var/lib/teleport
| Follow the Docker-Compose Getting Started Guide
If you wish to deploy Teleport inside a Docker container:
# This command will pull the Teleport container image for version 8
docker pull public.ecr.aws/gravitational/teleport:8
View latest tags on Amazon ECR Public | gravitational/teleport
Follow the instructions in the docker/README file.
To run a full test suite locally, see the test dependecies list
The teleport
repository contains the Teleport daemon binary (written in Go) and a web UI written in Javascript (a git submodule located in the webassets/
directory).
If your intention is to build and deploy for use in a production infrastructure a released tag should be used. The default branch, master
, is the current development branch for an upcoming major version. Get the latest release tags listed at https://goteleport.com/download/ and then use that tag in the git clone
. For example git clone https://github.com/gravitational/teleport.git -b v9.1.2
gets release v9.1.2.
It is often easiest to build with Docker, which ensures that all required tooling is available for the build. To execute a dockerized build, ensure that docker is installed and running, and execute:
make -C build.assets build-binaries
Ensure you have installed correct versions of necessary dependencies:
Go
version from go.modRust
and Cargo
version in build.assets/Makefile (search for RUST_VERSION
)tsh
version > 10.x
with FIDO support, you will need libfido
and openssl 1.1
installed locallyFor an example of Dev Environment setup on a Mac, see these instructions.
Important
- The Go compiler is somewhat sensitive to the amount of memory: you will need at least 1GB of virtual memory to compile Teleport. A 512MB instance without swap will not work.
- This will build the latest version of Teleport, regardless of whether it is stable. If you want to build the latest stable release, run
git checkout
andgit submodule update --recursive
to the corresponding tag (for example,- run
git checkout v8.0.0
) before performing a build.
Get the source
git clone https://github.com/gravitational/teleport.git
cd teleport
To perform a build
make full
To build tsh
with Apple TouchID support enabled:
Important
tsh
binaries with Touch ID support are only functional using binaries signed with Teleport's Apple Developer ID and notarized by Apple. If you are a Teleport maintainer, ask the team for access.
make build/tsh TOUCHID=yes
To build tsh
with libfido
:
make build/tsh FIDO2=dynamic
On a Mac, with libfido
and openssl 1.1
installed via homebrew
export PKG_CONFIG_PATH="$(brew --prefix openssl@1.1)/lib/pkgconfig"
make build/tsh FIDO2=dynamic
If the build succeeds, the installer will place the binaries in the build
directory.
Before starting, create default data directories:
sudo mkdir -p -m0700 /var/lib/teleport
sudo chown $USER /var/lib/teleport
The Teleport Web UI resides in the Gravitational Webapps repo.
To clone this repository and rebuild the Teleport UI package, run the following commands:
git clone git@github.com:gravitational/webapps.git
cd webapps
make build-teleport
Then you can replace Teleport Web UI files with the files from the newly-generated /dist
folder.
To enable speedy iterations on the Web UI, you can run a local web-dev server.
You can also tell Teleport to load the Web UI assets from the source directory. To enable this behavior, set the environment variable DEBUG=1
and rebuild with the default target:
# Run Teleport as a single-node cluster in development mode:
DEBUG=1 ./build/teleport start -d
Keep the server running in this mode, and make your UI changes in /dist
directory. For instructions about how to update the Web UI, read the webapps
README file.
After you commit a change to the webapps
repo, you need to update the Web UI assets in the webassets/
git submodule.
Run make update-webassets
to update the webassets
repo and create a PR for teleport
to update its git submodule.
You will need to have the gh
utility installed on your system for the script to work. For installation instructions, read the GitHub CLI installation documentation.
All dependencies are managed using Go modules. Here are the instructions for some common tasks:
Latest version:
go get github.com/new/dependency
and update the source to use this dependency.
To get a specific version, use go get github.com/new/dependency@version
instead.
go get github.com/new/dependency@version
go get -u github.com/new/dependency
go get -u all
Why is a specific package imported?
go mod why $pkgname
Why is a specific module imported?
go mod why -m $modname
Why is a specific version of a module imported?
go mod graph | grep $modname
The Teleport creators used to work together at Rackspace. We noticed that most cloud computing users struggle with setting up and configuring infrastructure security because popular tools, while flexible, are complex to understand and expensive to maintain. Additionally, most organizations use multiple infrastructure form factors such as several cloud providers, multiple cloud accounts, servers in colocation, and even smart devices. Some of those devices run on untrusted networks, behind third-party firewalls. This only magnifies complexity and increases operational overhead.
We had a choice, either start a security consulting business or build a solution that's dead-easy to use and understand. A real-time representation of all of your servers in the same room as you, as if they were magically teleported. Thus, Teleport was born!
We offer a few different options for support. First of all, we try to provide clear and comprehensive documentation. The docs are also in Github, so feel free to create a PR or file an issue if you have ideas for improvements. If you still have questions after reviewing our docs, you can also:
Teleport is used by leading companies to enable engineers to quickly access any computing resource anywhere. Teleport has completed several security audits from the nationally recognized technology security companies. We make some our audits public, view our latest audit reports.. We are comfortable with the use of Teleport from a security perspective.
You can see the list of companies who use Teleport in production on the Teleport product page.
You can find the latest stable Teleport build on our Releases page.
Teleport was created by Gravitational Inc. We have built Teleport by borrowing from our previous experiences at Rackspace. Learn more about Teleport and our history.
Read our Blog: https://goteleport.com/blog/
Read our Documentation: https://goteleport.com/docs/getting-started/
Author: Gravitational
Source Code: https://github.com/gravitational/teleport
License: Apache-2.0 license
1665061140
Cloud enhanced SSH client replacement with host auto-completion.
In times of digital clouds, servers come and go, and you barely remember its names and addresses. This tiny tool provide fuzzy search (yeah like SublimeText) for your instances list, based on tags, security groups and names.
Automatic installation. Just run following code in your terminal
bash <(curl -# https://buger.github.io/cloud-ssh/install.sh)
Manual installation - download and unpack latest release: http://github.com/buger/cloud-ssh/releases
sh-3.2$ # Lets say i want connect to server called stage-matching
sh-3.2$ ./cloud-ssh leon@stama
Found config: /Users/buger/.ssh/cloud-ssh.yaml
Found clound instance:
Cloud: granify_ec2 Matched by: aws:autoscaling:groupName=stage-matching Addr: ec2-50-200-40-200.compute-1.amazonaws.com
Welcome to Ubuntu 12.04 LTS (GNU/Linux 3.2.0-25-virtual x86_64)
If there are more then 1 server matching your query, it will ask you to choose one:
sh-3.2$ # I want to check one of my CouchBase servers
sh-3.2$ ./cloud-ssh ubuntu@couch
Found config: /Users/buger/.ssh/cloud-ssh.yaml
Found multiple instances:
1) Cloud: granify_ec2 Matched by: Name=couchbase-02 Addr: ec2-50-200-40-201.compute-1.amazonaws.com
2) Cloud: granify_ec2 Matched by: Name=couchbase-03 Addr: ec2-50-200-40-202.compute-1.amazonaws.com
3) Cloud: granify_ec2 Matched by: Name=couchbase-04 Addr: ec2-50-200-40-203.compute-1.amazonaws.com
4) Cloud: granify_ec2 Matched by: Name=couchbase-01 Addr: ec2-50-200-40-204.compute-1.amazonaws.com
5) Cloud: granify_ec2 Matched by: Name=couchbase-05 Addr: ec2-50-200-40-205.compute-1.amazonaws.com
Choose instance: 1
Welcome to Ubuntu 12.04.4 LTS (GNU/Linux 3.2.0-58-virtual x86_64)
Nice, right? More over, cloud-ssh can act as full ssh replacement, since it just forward all calls to ssh command.
By default it checks your environment for AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY environment variables. If you want advanced configuration you can create cloud-ssh.yaml
in one of this directories: ./ (current), ~/.ssh/, /etc/
Note that you can define multiple clouds, per provider, if you have multi-datacenter setup or just different clients. Cloud name will be included into search term, so you can filter by it too!
Right now only 2 data cloud providers supported: Amazon EC2 and DigitalOcean.
Example configuration:
gran_ec2: # cloud name, used when searching
provider: aws
region: us-east-1
access_key: AAAAAAAAAAAAAAAAA
secret_key: BBBBBBBBBBBBBBBBBBBBBBBBB
default_user: ubuntu
gran_digital:
provider: digital_ocean
client_id: 111111111111111111
api_key: 22222222222222222
Totally yes! Actually it just SSH wrapper, so all SSH command options will work as before.
Official site: https://buger.github.io/cloud-ssh/
Author: Buger
Source Code: https://github.com/buger/cloud-ssh
1665012000
SSH2 client and server modules written in pure JavaScript for node.js.
Development/testing is done against OpenSSH (8.7 currently).
Changes (breaking or otherwise) in v1.0.0 can be found here.
cpu-features
is set as an optional package dependency (you do not need to install it explicitly/separately from ssh2
) that will be automatically built and used if possible. See the project's documentation for its own requirements.npm install ssh2
const { readFileSync } = require('fs');
const { Client } = require('ssh2');
const conn = new Client();
conn.on('ready', () => {
console.log('Client :: ready');
conn.exec('uptime', (err, stream) => {
if (err) throw err;
stream.on('close', (code, signal) => {
console.log('Stream :: close :: code: ' + code + ', signal: ' + signal);
conn.end();
}).on('data', (data) => {
console.log('STDOUT: ' + data);
}).stderr.on('data', (data) => {
console.log('STDERR: ' + data);
});
});
}).connect({
host: '192.168.100.100',
port: 22,
username: 'frylock',
privateKey: readFileSync('/path/to/my/key')
});
// example output:
// Client :: ready
// STDOUT: 17:41:15 up 22 days, 18:09, 1 user, load average: 0.00, 0.01, 0.05
//
// Stream :: exit :: code: 0, signal: undefined
// Stream :: close
const { readFileSync } = require('fs');
const { Client } = require('ssh2');
const conn = new Client();
conn.on('ready', () => {
console.log('Client :: ready');
conn.shell((err, stream) => {
if (err) throw err;
stream.on('close', () => {
console.log('Stream :: close');
conn.end();
}).on('data', (data) => {
console.log('OUTPUT: ' + data);
});
stream.end('ls -l\nexit\n');
});
}).connect({
host: '192.168.100.100',
port: 22,
username: 'frylock',
privateKey: readFileSync('/path/to/my/key')
});
// example output:
// Client :: ready
// STDOUT: Last login: Sun Jun 15 09:37:21 2014 from 192.168.100.100
//
// STDOUT: ls -l
// exit
//
// STDOUT: frylock@athf:~$ ls -l
//
// STDOUT: total 8
//
// STDOUT: drwxr-xr-x 2 frylock frylock 4096 Nov 18 2012 mydir
//
// STDOUT: -rw-r--r-- 1 frylock frylock 25 Apr 11 2013 test.txt
//
// STDOUT: frylock@athf:~$ exit
//
// STDOUT: logout
//
// Stream :: close
const { Client } = require('ssh2');
const conn = new Client();
conn.on('ready', () => {
console.log('Client :: ready');
conn.forwardOut('192.168.100.102', 8000, '127.0.0.1', 80, (err, stream) => {
if (err) throw err;
stream.on('close', () => {
console.log('TCP :: CLOSED');
conn.end();
}).on('data', (data) => {
console.log('TCP :: DATA: ' + data);
}).end([
'HEAD / HTTP/1.1',
'User-Agent: curl/7.27.0',
'Host: 127.0.0.1',
'Accept: */*',
'Connection: close',
'',
''
].join('\r\n'));
});
}).connect({
host: '192.168.100.100',
port: 22,
username: 'frylock',
password: 'nodejsrules'
});
// example output:
// Client :: ready
// TCP :: DATA: HTTP/1.1 200 OK
// Date: Thu, 15 Nov 2012 13:52:58 GMT
// Server: Apache/2.2.22 (Ubuntu)
// X-Powered-By: PHP/5.4.6-1ubuntu1
// Last-Modified: Thu, 01 Jan 1970 00:00:00 GMT
// Content-Encoding: gzip
// Vary: Accept-Encoding
// Connection: close
// Content-Type: text/html; charset=UTF-8
//
//
// TCP :: CLOSED
const { Client } = require('ssh2');
const conn = new Client();
conn.on('ready', () => {
console.log('Client :: ready');
conn.forwardIn('127.0.0.1', 8000, (err) => {
if (err) throw err;
console.log('Listening for connections on server on port 8000!');
});
}).on('tcp connection', (info, accept, reject) => {
console.log('TCP :: INCOMING CONNECTION:');
console.dir(info);
accept().on('close', () => {
console.log('TCP :: CLOSED');
}).on('data', (data) => {
console.log('TCP :: DATA: ' + data);
}).end([
'HTTP/1.1 404 Not Found',
'Date: Thu, 15 Nov 2012 02:07:58 GMT',
'Server: ForwardedConnection',
'Content-Length: 0',
'Connection: close',
'',
''
].join('\r\n'));
}).connect({
host: '192.168.100.100',
port: 22,
username: 'frylock',
password: 'nodejsrules'
});
// example output:
// Client :: ready
// Listening for connections on server on port 8000!
// (.... then from another terminal on the server: `curl -I http://127.0.0.1:8000`)
// TCP :: INCOMING CONNECTION: { destIP: '127.0.0.1',
// destPort: 8000,
// srcIP: '127.0.0.1',
// srcPort: 41969 }
// TCP DATA: HEAD / HTTP/1.1
// User-Agent: curl/7.27.0
// Host: 127.0.0.1:8000
// Accept: */*
//
//
// TCP :: CLOSED
const { Client } = require('ssh2');
const conn = new Client();
conn.on('ready', () => {
console.log('Client :: ready');
conn.sftp((err, sftp) => {
if (err) throw err;
sftp.readdir('foo', (err, list) => {
if (err) throw err;
console.dir(list);
conn.end();
});
});
}).connect({
host: '192.168.100.100',
port: 22,
username: 'frylock',
password: 'nodejsrules'
});
// example output:
// Client :: ready
// [ { filename: 'test.txt',
// longname: '-rw-r--r-- 1 frylock frylock 12 Nov 18 11:05 test.txt',
// attrs:
// { size: 12,
// uid: 1000,
// gid: 1000,
// mode: 33188,
// atime: 1353254750,
// mtime: 1353254744 } },
// { filename: 'mydir',
// longname: 'drwxr-xr-x 2 frylock frylock 4096 Nov 18 15:03 mydir',
// attrs:
// { size: 1048576,
// uid: 1000,
// gid: 1000,
// mode: 16877,
// atime: 1353269007,
// mtime: 1353269007 } } ]
const { Client } = require('ssh2');
const conn1 = new Client();
const conn2 = new Client();
// Checks uptime on 10.1.1.40 via 192.168.1.1
conn1.on('ready', () => {
console.log('FIRST :: connection ready');
// Alternatively, you could use something like netcat or socat with exec()
// instead of forwardOut(), depending on what the server allows
conn1.forwardOut('127.0.0.1', 12345, '10.1.1.40', 22, (err, stream) => {
if (err) {
console.log('FIRST :: forwardOut error: ' + err);
return conn1.end();
}
conn2.connect({
sock: stream,
username: 'user2',
password: 'password2',
});
});
}).connect({
host: '192.168.1.1',
username: 'user1',
password: 'password1',
});
conn2.on('ready', () => {
// This connection is the one to 10.1.1.40
console.log('SECOND :: connection ready');
conn2.exec('uptime', (err, stream) => {
if (err) {
console.log('SECOND :: exec error: ' + err);
return conn1.end();
}
stream.on('close', () => {
conn1.end(); // close parent (and this) connection
}).on('data', (data) => {
console.log(data.toString());
});
});
});
const { Socket } = require('net');
const { Client } = require('ssh2');
const conn = new Client();
conn.on('x11', (info, accept, reject) => {
const xserversock = new net.Socket();
xserversock.on('connect', () => {
const xclientsock = accept();
xclientsock.pipe(xserversock).pipe(xclientsock);
});
// connects to localhost:0.0
xserversock.connect(6000, 'localhost');
});
conn.on('ready', () => {
conn.exec('xeyes', { x11: true }, (err, stream) => {
if (err) throw err;
let code = 0;
stream.on('close', () => {
if (code !== 0)
console.log('Do you have X11 forwarding enabled on your SSH server?');
conn.end();
}).on('exit', (exitcode) => {
code = exitcode;
});
});
}).connect({
host: '192.168.1.1',
username: 'foo',
password: 'bar'
});
const socks = require('socksv5');
const { Client } = require('ssh2');
const sshConfig = {
host: '192.168.100.1',
port: 22,
username: 'nodejs',
password: 'rules'
};
socks.createServer((info, accept, deny) => {
// NOTE: you could just use one ssh2 client connection for all forwards, but
// you could run into server-imposed limits if you have too many forwards open
// at any given time
const conn = new Client();
conn.on('ready', () => {
conn.forwardOut(info.srcAddr,
info.srcPort,
info.dstAddr,
info.dstPort,
(err, stream) => {
if (err) {
conn.end();
return deny();
}
const clientSocket = accept(true);
if (clientSocket) {
stream.pipe(clientSocket).pipe(stream).on('close', () => {
conn.end();
});
} else {
conn.end();
}
});
}).on('error', (err) => {
deny();
}).connect(sshConfig);
}).listen(1080, 'localhost', () => {
console.log('SOCKSv5 proxy server started on port 1080');
}).useAuth(socks.auth.None());
// test with cURL:
// curl -i --socks5 localhost:1080 google.com
const http = require('http');
const { Client, HTTPAgent, HTTPSAgent } = require('ssh2');
const sshConfig = {
host: '192.168.100.1',
port: 22,
username: 'nodejs',
password: 'rules'
};
// Use `HTTPSAgent` instead for an HTTPS request
const agent = new HTTPAgent(sshConfig);
http.get({
host: '192.168.200.1',
agent,
headers: { Connection: 'close' }
}, (res) => {
console.log(res.statusCode);
console.dir(res.headers);
res.resume();
});
const { Client } = require('ssh2');
const xmlhello = `
<?xml version="1.0" encoding="UTF-8"?>
<hello xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<capabilities>
<capability>urn:ietf:params:netconf:base:1.0</capability>
</capabilities>
</hello>]]>]]>`;
const conn = new Client();
conn.on('ready', () => {
console.log('Client :: ready');
conn.subsys('netconf', (err, stream) => {
if (err) throw err;
stream.on('data', (data) => {
console.log(data);
}).write(xmlhello);
});
}).connect({
host: '1.2.3.4',
port: 22,
username: 'blargh',
password: 'honk'
});
const { timingSafeEqual } = require('crypto');
const { readFileSync } = require('fs');
const { inspect } = require('util');
const { utils: { parseKey }, Server } = require('ssh2');
const allowedUser = Buffer.from('foo');
const allowedPassword = Buffer.from('bar');
const allowedPubKey = parseKey(readFileSync('foo.pub'));
function checkValue(input, allowed) {
const autoReject = (input.length !== allowed.length);
if (autoReject) {
// Prevent leaking length information by always making a comparison with the
// same input when lengths don't match what we expect ...
allowed = input;
}
const isMatch = timingSafeEqual(input, allowed);
return (!autoReject && isMatch);
}
new Server({
hostKeys: [readFileSync('host.key')]
}, (client) => {
console.log('Client connected!');
client.on('authentication', (ctx) => {
let allowed = true;
if (!checkValue(Buffer.from(ctx.username), allowedUser))
allowed = false;
switch (ctx.method) {
case 'password':
if (!checkValue(Buffer.from(ctx.password), allowedPassword))
return ctx.reject();
break;
case 'publickey':
if (ctx.key.algo !== allowedPubKey.type
|| !checkValue(ctx.key.data, allowedPubKey.getPublicSSH())
|| (ctx.signature && allowedPubKey.verify(ctx.blob, ctx.signature) !== true)) {
return ctx.reject();
}
break;
default:
return ctx.reject();
}
if (allowed)
ctx.accept();
else
ctx.reject();
}).on('ready', () => {
console.log('Client authenticated!');
client.on('session', (accept, reject) => {
const session = accept();
session.once('exec', (accept, reject, info) => {
console.log('Client wants to execute: ' + inspect(info.command));
const stream = accept();
stream.stderr.write('Oh no, the dreaded errors!\n');
stream.write('Just kidding about the errors!\n');
stream.exit(0);
stream.end();
});
});
}).on('close', () => {
console.log('Client disconnected');
});
}).listen(0, '127.0.0.1', function() {
console.log('Listening on port ' + this.address().port);
});
const { timingSafeEqual } = require('crypto');
const { readFileSync } = require('fs');
const { inspect } = require('util');
const {
Server,
sftp: {
OPEN_MODE,
STATUS_CODE,
},
} = require('ssh2');
const allowedUser = Buffer.from('foo');
const allowedPassword = Buffer.from('bar');
function checkValue(input, allowed) {
const autoReject = (input.length !== allowed.length);
if (autoReject) {
// Prevent leaking length information by always making a comparison with the
// same input when lengths don't match what we expect ...
allowed = input;
}
const isMatch = timingSafeEqual(input, allowed);
return (!autoReject && isMatch);
}
// This simple SFTP server implements file uploading where the contents get
// ignored ...
new ssh2.Server({
hostKeys: [readFileSync('host.key')]
}, (client) => {
console.log('Client connected!');
client.on('authentication', (ctx) => {
let allowed = true;
if (!checkValue(Buffer.from(ctx.username), allowedUser))
allowed = false;
switch (ctx.method) {
case 'password':
if (!checkValue(Buffer.from(ctx.password), allowedPassword))
return ctx.reject();
break;
default:
return ctx.reject();
}
if (allowed)
ctx.accept();
else
ctx.reject();
}).on('ready', () => {
console.log('Client authenticated!');
client.on('session', (accept, reject) => {
const session = accept();
session.on('sftp', (accept, reject) => {
console.log('Client SFTP session');
const openFiles = new Map();
let handleCount = 0;
const sftp = accept();
sftp.on('OPEN', (reqid, filename, flags, attrs) => {
// Only allow opening /tmp/foo.txt for writing
if (filename !== '/tmp/foo.txt' || !(flags & OPEN_MODE.WRITE))
return sftp.status(reqid, STATUS_CODE.FAILURE);
// Create a fake handle to return to the client, this could easily
// be a real file descriptor number for example if actually opening
// a file on disk
const handle = Buffer.alloc(4);
openFiles.set(handleCount, true);
handle.writeUInt32BE(handleCount++, 0);
console.log('Opening file for write')
sftp.handle(reqid, handle);
}).on('WRITE', (reqid, handle, offset, data) => {
if (handle.length !== 4
|| !openFiles.has(handle.readUInt32BE(0))) {
return sftp.status(reqid, STATUS_CODE.FAILURE);
}
// Fake the write operation
sftp.status(reqid, STATUS_CODE.OK);
console.log('Write to file at offset ${offset}: ${inspect(data)}');
}).on('CLOSE', (reqid, handle) => {
let fnum;
if (handle.length !== 4
|| !openFiles.has(fnum = handle.readUInt32BE(0))) {
return sftp.status(reqid, STATUS_CODE.FAILURE);
}
console.log('Closing file');
openFiles.delete(fnum);
sftp.status(reqid, STATUS_CODE.OK);
});
});
});
}).on('close', () => {
console.log('Client disconnected');
});
}).listen(0, '127.0.0.1', function() {
console.log('Listening on port ' + this.address().port);
});
You can find more examples in the examples
directory of this repository.
require('ssh2').Client
is the Client constructor.
require('ssh2').Server
is the Server constructor.
require('ssh2').utils
is an object containing some useful utilities.
require('ssh2').HTTPAgent
is an http.Agent
constructor.
require('ssh2').HTTPSAgent
is an https.Agent
constructor. Its API is the same as HTTPAgent
except it's for HTTPS connections.
require('ssh2').AgentProtocol
is a Duplex stream class that aids in communicating over the OpenSSH agent protocol.
require('ssh2').BaseAgent
is a base class for creating custom authentication agents.
require('ssh2').createAgent
is a helper function that creates a new agent instance using the same logic as the agent
configuration option: if the platform is Windows and it's the value "pageant", it creates a PageantAgent
, otherwise if it's not a path to a Windows pipe it creates a CygwinAgent
. In all other cases, it creates an OpenSSHAgent
.
require('ssh2').CygwinAgent
is an agent class implementation that communicates with agents in a Cygwin environment.
require('ssh2').OpenSSHAgent
is an agent class implementation that communicates with OpenSSH agents over a UNIX socket.
require('ssh2').PageantAgent
is an agent class implementation that communicates with Pageant agent processes.
banner(< string >message, < string >language) - A notice was sent by the server upon connection.
change password(< string >prompt, < function >done) - If using password-based user authentication, the server has requested that the user's password be changed. Call done
with the new password.
close() - The socket was closed.
end() - The socket was disconnected.
error(< Error >err) - An error occurred. A 'level' property indicates 'client-socket' for socket-level errors and 'client-ssh' for SSH disconnection messages. In the case of 'client-ssh' messages, there may be a 'description' property that provides more detail.
handshake(< object >negotiated) - Emitted when a handshake has completed (either initial or rekey). negotiated
contains the negotiated details of the handshake and is of the form:
// In this particular case `mac` is empty because there is no separate MAC
// because it's integrated into AES in GCM mode
{ kex: 'ecdh-sha2-nistp256',
srvHostKey: 'rsa-sha2-512',
cs: { // Client to server algorithms
cipher: 'aes128-gcm',
mac: '',
compress: 'none',
lang: ''
},
sc: { // Server to client algorithms
cipher: 'aes128-gcm',
mac: '',
compress: 'none',
lang: ''
}
}
hostkeys(< array >keys) - Emitted when the server announces its available host keys. keys
is the list of parsed (using parseKey()
) host public keys.
keyboard-interactive(< string >name, < string >instructions, < string >instructionsLang, < array >prompts, < function >finish) - The server is asking for replies to the given prompts
for keyboard-interactive user authentication. name
is generally what you'd use as a window title (for GUI apps). prompts
is an array of { prompt: 'Password: ', echo: false }
style objects (here echo
indicates whether user input should be displayed on the screen). The answers for all prompts must be provided as an array of strings and passed to finish
when you are ready to continue. Note: It's possible for the server to come back and ask more questions.
ready() - Authentication was successful.
rekey() - Emitted when a rekeying operation has completed (either client or server-initiated).
tcp connection(< object >details, < function >accept, < function >reject) - An incoming forwarded TCP connection is being requested. Calling accept
accepts the connection and returns a Channel
object. Calling reject
rejects the connection and no further action is needed. details
contains:
destIP - string - The remote IP the connection was received on (given in earlier call to forwardIn()
).
destPort - integer - The remote port the connection was received on (given in earlier call to forwardIn()
).
srcIP - string - The originating IP of the connection.
srcPort - integer - The originating port of the connection.
unix connection(< object >details, < function >accept, < function >reject) - An incoming forwarded UNIX socket connection is being requested. Calling accept
accepts the connection and returns a Channel
object. Calling reject
rejects the connection and no further action is needed. details
contains:
x11(< object >details, < function >accept, < function >reject) - An incoming X11 connection is being requested. Calling accept
accepts the connection and returns a Channel
object. Calling reject
rejects the connection and no further action is needed. details
contains:
srcIP - string - The originating IP of the connection.
srcPort - integer - The originating port of the connection.
(constructor)() - Creates and returns a new Client instance.
connect(< object >config) - (void) - Attempts a connection to a server using the information given in config
:
agent - string - Path to ssh-agent's UNIX socket for ssh-agent-based user authentication. Windows users: set to 'pageant' for authenticating with Pageant or (actual) path to a cygwin "UNIX socket." Default: (none)
agentForward - boolean - Set to true
to use OpenSSH agent forwarding (auth-agent@openssh.com
) for the life of the connection. agent
must also be set to use this feature. Default: false
algorithms - object - This option allows you to explicitly override the default transport layer algorithms used for the connection. The value for each category must either be an array of valid algorithm names to set an exact list (with the most preferable first) or an object containing append
, prepend
, and/or remove
properties that each contain an array of algorithm names or RegExps to match to adjust default lists for each category. Valid keys:
cipher - mixed - Ciphers.
chacha20-poly1305@openssh.com
(priority of chacha20-poly1305 may vary depending upon CPU and/or optional binding availability)aes128-gcm
aes128-gcm@openssh.com
aes256-gcm
aes256-gcm@openssh.com
aes128-ctr
aes192-ctr
aes256-ctr
3des-cbc
aes256-cbc
aes192-cbc
aes128-cbc
arcfour256
arcfour128
arcfour
blowfish-cbc
cast128-cbc
compress - mixed - Compression algorithms.
none
zlib@openssh.com
zlib
hmac - mixed - (H)MAC algorithms.
hmac-sha2-256-etm@openssh.com
hmac-sha2-512-etm@openssh.com
hmac-sha1-etm@openssh.com
hmac-sha2-256
hmac-sha2-512
hmac-sha1
hmac-md5
hmac-sha2-256-96
hmac-sha2-512-96
hmac-ripemd160
hmac-sha1-96
hmac-md5-96
kex - mixed - Key exchange algorithms.
curve25519-sha256
(node v14.0.0+)curve25519-sha256@libssh.org
(node v14.0.0+)ecdh-sha2-nistp256
ecdh-sha2-nistp384
ecdh-sha2-nistp521
diffie-hellman-group-exchange-sha256
diffie-hellman-group14-sha256
diffie-hellman-group15-sha512
diffie-hellman-group16-sha512
diffie-hellman-group17-sha512
diffie-hellman-group18-sha512
diffie-hellman-group-exchange-sha1
diffie-hellman-group14-sha1
diffie-hellman-group1-sha1
serverHostKey - mixed - Server host key formats.
ssh-ed25519
(node v12.0.0+)ecdsa-sha2-nistp256
ecdsa-sha2-nistp384
ecdsa-sha2-nistp521
rsa-sha2-512
rsa-sha2-256
ssh-rsa
ssh-dss
authHandler - mixed - Must be an array of objects as described below, an array of strings containing valid authentication method names (username and credentials are pulled from the object passed to connect()
), or a function with parameters (methodsLeft, partialSuccess, callback)
where methodsLeft
and partialSuccess
are null
on the first authentication attempt, otherwise are an array and boolean respectively. Return or call callback()
with either the name of the authentication method or an object containing the method name along with method-specific details to try next (return/pass false
to signal no more methods to try). Valid method names are: 'none', 'password', 'publickey', 'agent', 'keyboard-interactive', 'hostbased'
. Default: function that follows a set method order: None -> Password -> Private Key -> Agent (-> keyboard-interactive if tryKeyboard
is true
) -> Hostbased
When returning or calling callback()
with an object, it can take one of the following forms:
{
type: 'none',
username: 'foo',
}
{
type: 'password'
username: 'foo',
password: 'bar',
}
{
type: 'publickey'
username: 'foo',
// Can be a string, Buffer, or parsed key containing a private key
key: ...,
// `passphrase` only required for encrypted keys
passphrase: ...,
}
{
type: 'hostbased'
username: 'foo',
localHostname: 'baz',
localUsername: 'quux',
// Can be a string, Buffer, or parsed key containing a private key
key: ...,
// `passphrase` only required for encrypted keys
passphrase: ...,
}
{
type: 'agent'
username: 'foo',
// Can be a string that is interpreted exactly like the `agent`
// connection config option or can be a custom agent
// object/instance that extends and implements `BaseAgent`
agent: ...,
}
{
type: 'keyboard-interactive'
username: 'foo',
// This works exactly the same way as a 'keyboard-interactive'
// Client event handler
prompt: (name, instructions, instructionsLang, prompts, finish) => {
// ...
},
}
debug - function - Set this to a function that receives a single string argument to get detailed (local) debug information. Default: (none)
forceIPv4 - boolean - Only connect via resolved IPv4 address for host
. Default: false
forceIPv6 - boolean - Only connect via resolved IPv6 address for host
. Default: false
host - string - Hostname or IP address of the server. Default: 'localhost'
hostHash - string - Any valid hash algorithm supported by node. The host's key is hashed using this algorithm and passed to the hostVerifier function as a hex string. Default: (none)
hostVerifier - function - Function with parameters (hashedKey[, callback])
where hashedKey
is a string hex hash of the host's key for verification purposes. Return true
to continue with the handshake or false
to reject and disconnect, or call callback()
with true
or false
if you need to perform asynchronous verification. Default: (auto-accept if hostVerifier
is not set)
keepaliveCountMax - integer - How many consecutive, unanswered SSH-level keepalive packets that can be sent to the server before disconnection (similar to OpenSSH's ServerAliveCountMax config option). Default: 3
keepaliveInterval - integer - How often (in milliseconds) to send SSH-level keepalive packets to the server (in a similar way as OpenSSH's ServerAliveInterval config option). Set to 0 to disable. Default: 0
localAddress - string - IP address of the network interface to use to connect to the server. Default: (none -- determined by OS)
localHostname - string - Along with localUsername and privateKey, set this to a non-empty string for hostbased user authentication. Default: (none)
localPort - string - The local port number to connect from. Default: (none -- determined by OS)
localUsername - string - Along with localHostname and privateKey, set this to a non-empty string for hostbased user authentication. Default: (none)
passphrase - string - For an encrypted privateKey
, this is the passphrase used to decrypt it. Default: (none)
password - string - Password for password-based user authentication. Default: (none)
port - integer - Port number of the server. Default: 22
privateKey - mixed - Buffer or string that contains a private key for either key-based or hostbased user authentication (OpenSSH format). Default: (none)
readyTimeout - integer - How long (in milliseconds) to wait for the SSH handshake to complete. Default: 20000
sock - ReadableStream - A ReadableStream to use for communicating with the server instead of creating and using a new TCP connection (useful for connection hopping).
strictVendor - boolean - Performs a strict server vendor check before sending vendor-specific requests, etc. (e.g. check for OpenSSH server when using openssh_noMoreSessions()
) Default: true
tryKeyboard - boolean - Try keyboard-interactive user authentication if primary user authentication method fails. If you set this to true
, you need to handle the keyboard-interactive
event. Default: false
username - string - Username for authentication. Default: (none)
end() - (void) - Disconnects the socket.
exec(< string >command[, < object >options], < function >callback) - (void) - Executes command
on the server. callback
has 2 parameters: < Error >err, < Channel >stream. Valid options
properties are:
env - object - An environment to use for the execution of the command.
pty - mixed - 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).
x11 - mixed - Set to true
to use defaults below, set to a number to specify a specific screen number, or an object with the following valid properties:
cookie - mixed - The authentication cookie. Can be a hex string or a Buffer containing the raw cookie value (which will be converted to a hex string). Default: (random 16 byte value)
protocol - string - The authentication protocol name. Default: 'MIT-MAGIC-COOKIE-1'
screen - number - Screen number to use Default: 0
single - boolean - Allow just a single connection? Default: false
forwardIn(< string >remoteAddr, < integer >remotePort, < function >callback) - (void) - Bind to remoteAddr
on remotePort
on the server and forward incoming TCP connections. callback
has 2 parameters: < Error >err, < integer >port (port
is the assigned port number if remotePort
was 0). Here are some special values for remoteAddr
and their associated binding behaviors:
'' - Connections are to be accepted on all protocol families supported by the server.
'0.0.0.0' - Listen on all IPv4 addresses.
'::' - Listen on all IPv6 addresses.
'localhost' - Listen on all protocol families supported by the server on loopback addresses only.
'127.0.0.1' and '::1' - Listen on the loopback interfaces for IPv4 and IPv6, respectively.
forwardOut(< string >srcIP, < integer >srcPort, < string >dstIP, < integer >dstPort, < function >callback) - (void) - Open a connection with srcIP
and srcPort
as the originating address and port and dstIP
and dstPort
as the remote destination address and port. callback
has 2 parameters: < Error >err, < Channel >stream.
openssh_forwardInStreamLocal(< string >socketPath, < function >callback) - (void) - OpenSSH extension that binds to a UNIX domain socket at socketPath
on the server and forwards incoming connections. callback
has 1 parameter: < Error >err.
openssh_forwardOutStreamLocal(< string >socketPath, < function >callback) - (void) - OpenSSH extension that opens a connection to a UNIX domain socket at socketPath
on the server. callback
has 2 parameters: < Error >err, < Channel >stream.
openssh_noMoreSessions(< function >callback) - (void) - OpenSSH extension that sends a request to reject any new sessions (e.g. exec, shell, sftp, subsys) for this connection. callback
has 1 parameter: < Error >err.
openssh_unforwardInStreamLocal(< string >socketPath, < function >callback) - (void) - OpenSSH extension that unbinds from a UNIX domain socket at socketPath
on the server and stops forwarding incoming connections. callback
has 1 parameter: < Error >err.
rekey([< function >callback]) - (void) - Initiates a rekey with the server. If callback
is supplied, it is added as a one-time handler for the rekey
event.
sftp(< function >callback) - (void) - Starts an SFTP session. callback
has 2 parameters: < Error >err, < SFTP >sftp. For methods available on sftp
, see the SFTP
client documentation.
shell([[< mixed >window,] < object >options]< function >callback) - (void) - Starts an interactive shell session on the server, with an optional window
object containing pseudo-tty settings (see 'Pseudo-TTY settings'). If window === false
, then no pseudo-tty is allocated. options
supports the x11
and env
options as described in exec()
. callback
has 2 parameters: < Error >err, < Channel >stream.
subsys(< string >subsystem, < function >callback) - (void) - Invokes subsystem
on the server. callback
has 2 parameters: < Error >err, < Channel >stream.
unforwardIn(< string >remoteAddr, < integer >remotePort, < function >callback) - (void) - Unbind from remoteAddr
on remotePort
on the server and stop forwarding incoming TCP connections. Until callback
is called, more connections may still come in. callback
has 1 parameter: < Error >err.
connection(< Connection >client, < object >info) - A new client has connected. info
contains the following properties:
family - string - The remoteFamily
of the connection.
header - object - Information about the client's header:
identRaw - string - The raw client identification string.
versions - object - Various version information:
protocol - string - The SSH protocol version (always 1.99
or 2.0
).
software - string - The software name and version of the client.
comments - string - Any text that comes after the software name/version.
{ identRaw: 'SSH-2.0-OpenSSH_6.6.1p1 Ubuntu-2ubuntu2',
version: {
protocol: '2.0',
software: 'OpenSSH_6.6.1p1'
},
comments: 'Ubuntu-2ubuntu2' }
* **ip** - _string_ - The `remoteAddress` of the connection.
* **port** - _integer_ - The `remotePort` of the connection.
(constructor)(< object >config[, < function >connectionListener]) - Creates and returns a new Server instance. Server instances also have the same methods/properties/events as net.Server
. connectionListener
if supplied, is added as a connection
listener. Valid config
properties:
algorithms - object - This option allows you to explicitly override the default transport layer algorithms used for incoming client connections. Each value must be an array of valid algorithms for that category. The order of the algorithms in the arrays are important, with the most favorable being first. For a list of valid and default algorithm names, please review the documentation for the version of ssh2
used by this module. Valid keys:
cipher - array - Ciphers.
compress - array - Compression algorithms.
hmac - array - (H)MAC algorithms.
kex - array - Key exchange algorithms.
serverHostKey - array - Server host key formats.
banner - string - A message that is sent to clients once, right before authentication begins. Default: (none)
debug - function - Set this to a function that receives a single string argument to get detailed (local) debug information. Default: (none)
greeting - string - A message that is sent to clients immediately upon connection, before handshaking begins. Note: Most clients usually ignore this. Default: (none)
highWaterMark - integer - This is the highWaterMark
to use for the parser stream. Default: 32 * 1024
hostKeys - array - An array of either Buffers/strings that contain host private keys or objects in the format of { key: <Buffer/string>, passphrase: <string> }
for encrypted private keys. (Required) Default: (none)
ident - string - A custom server software name/version identifier. Default: 'ssh2js' + moduleVersion + 'srv'
injectSocket(< DuplexStream >socket) - Injects a bidirectional stream as though it were a TCP socket connection. Additionally, socket
should include net.Socket
-like properties to ensure the best compatibility (e.g. socket.remoteAddress
, socket.remotePort
, socket.remoteFamily
).
authentication(< AuthContext >ctx) - The client has requested authentication. ctx.username
contains the client username, ctx.method
contains the requested authentication method, and ctx.accept()
and ctx.reject([< Array >authMethodsLeft[, < Boolean >isPartialSuccess]])
are used to accept or reject the authentication request respectively. abort
is emitted if the client aborts the authentication request. Other properties/methods available on ctx
depends on the ctx.method
of authentication the client has requested:
hostbased
:
blob - Buffer - This contains the data to be verified that is passed to (along with the signature) key.verify()
where key
is a public key parsed with parseKey()
.
key - object - Contains information about the public key sent by the client:
algo - string - The name of the key algorithm (e.g. ssh-rsa
).
data - Buffer - The actual key data.
localHostname - string - The local hostname provided by the client.
localUsername - string - The local username provided by the client.
signature - Buffer - This contains a signature to be verified that is passed to (along with the blob) key.verify()
where key
is a public key parsed with parseKey()
.
keyboard-interactive
:
prompt(< array >prompts[, < string >title[, < string >instructions]], < function >callback) - (void) - Send prompts to the client. prompts
is an array of { prompt: 'Prompt text', echo: true }
objects (prompt
being the prompt text and echo
indicating whether the client's response to the prompt should be echoed to their display). callback
is called with (responses)
, where responses
is an array of string responses matching up to the prompts
.
submethods - array - A list of preferred authentication "sub-methods" sent by the client. This may be used to determine what (if any) prompts to send to the client.
password
:
password - string - This is the password sent by the client.
requestChange(< string >prompt, < function >callback) - (void) - Sends a password change request to the client. callback
is called with (newPassword)
, where newPassword
is the new password supplied by the client. You may accept, reject, or prompt for another password change after callback
is called.
publickey
:
blob - mixed - If the value is undefined
, the client is only checking the validity of the key
. If the value is a Buffer, then this contains the data to be verified that is passed to (along with the signature) key.verify()
where key
is a public key parsed with parseKey()
.
key - object - Contains information about the public key sent by the client:
algo - string - The name of the key algorithm (e.g. ssh-rsa
).
data - Buffer - The actual key data.
signature - mixed - If the value is undefined
, the client is only checking the validity of the key
. If the value is a Buffer, then this contains a signature to be verified that is passed to (along with the blob) key.verify()
where key
is a public key parsed with parseKey()
.
close() - The client socket was closed.
end() - The client socket disconnected.
error(< Error >err) - An error occurred.
handshake(< object >negotiated) - Emitted when a handshake has completed (either initial or rekey). negotiated
contains the negotiated details of the handshake and is of the form:
// In this particular case `mac` is empty because there is no separate MAC
// because it's integrated into AES in GCM mode
{ kex: 'ecdh-sha2-nistp256',
srvHostKey: 'rsa-sha2-512',
cs: { // Client to server algorithms
cipher: 'aes128-gcm',
mac: '',
compress: 'none',
lang: ''
},
sc: { // Server to client algorithms
cipher: 'aes128-gcm',
mac: '',
compress: 'none',
lang: ''
}
}
openssh.streamlocal(< function >accept, < function >reject, < object >info) - Emitted when the client has requested a connection to a UNIX domain socket. accept()
returns a new Channel instance representing the connection. info
contains:
ready() - Emitted when the client has been successfully authenticated.
rekey() - Emitted when a rekeying operation has completed (either client or server-initiated).
request(< mixed >accept, < mixed >reject, < string >name, < object >info) - Emitted when the client has sent a global request for name
(e.g. tcpip-forward
or cancel-tcpip-forward
). accept
and reject
are functions if the client requested a response. If bindPort === 0
, you should pass the chosen port to accept()
so that the client will know what port was bound. info
contains additional details about the request:
cancel-tcpip-forward
and tcpip-forward
:
bindAddr - string - The IP address to start/stop binding to.
bindPort - integer - The port to start/stop binding to.
cancel-streamlocal-forward@openssh.com
and streamlocal-forward@openssh.com
:
session(< function >accept, < function >reject) - Emitted when the client has requested a new session. Sessions are used to start interactive shells, execute commands, request X11 forwarding, etc. accept()
returns a new Session instance.
tcpip(< function >accept, < function >reject, < object >info) - Emitted when the client has requested an outbound (TCP) connection. accept()
returns a new Channel instance representing the connection. info
contains:
destIP - string - Destination IP address of outgoing connection.
destPort - string - Destination port of outgoing connection.
srcIP - string - Source IP address of outgoing connection.
srcPort - string - Source port of outgoing connection.
end() - (void) - Closes the client connection.
forwardOut(< string >boundAddr, < integer >boundPort, < string >remoteAddr, < integer >remotePort, < function >callback) - (void) - Alert the client of an incoming TCP connection on boundAddr
on port boundPort
from remoteAddr
on port remotePort
. callback
has 2 parameters: < Error >err, < Channel >stream.
openssh_forwardOutStreamLocal(< string >socketPath, < function >callback) - (void) - Alert the client of an incoming UNIX domain socket connection on socketPath
. callback
has 2 parameters: < Error >err, < Channel >stream.
rekey([< function >callback]) - (void) - Initiates a rekey with the client. If callback
is supplied, it is added as a one-time handler for the rekey
event.
x11(< string >originAddr, < integer >originPort, < function >callback) - (void) - Alert the client of an incoming X11 client connection from originAddr
on port originPort
. callback
has 2 parameters: < Error >err, < Channel >stream.
auth-agent(< mixed >accept, < mixed >reject) - The client has requested incoming ssh-agent requests be forwarded to them. accept
and reject
are functions if the client requested a response.
close() - The session was closed.
env(< mixed >accept, < mixed >reject, < object >info) - The client requested an environment variable to be set for this session. accept
and reject
are functions if the client requested a response. info
has these properties:
key - string - The environment variable's name.
value - string - The environment variable's value.
exec(< mixed >accept, < mixed >reject, < object >info) - The client has requested execution of a command string. accept
and reject
are functions if the client requested a response. accept()
returns a Channel for the command execution. info
has these properties:
pty(< mixed >accept, < mixed >reject, < object >info) - The client requested allocation of a pseudo-TTY for this session. accept
and reject
are functions if the client requested a response. info
has these properties:
cols - integer - The number of columns for the pseudo-TTY.
height - integer - The height of the pseudo-TTY in pixels.
modes - object - Contains the requested terminal modes of the pseudo-TTY keyed on the mode name with the value being the mode argument. (See the table at the end for valid names).
rows - integer - The number of rows for the pseudo-TTY.
width - integer - The width of the pseudo-TTY in pixels.
sftp(< mixed >accept, < mixed >reject) - The client has requested the SFTP subsystem. accept
and reject
are functions if the client requested a response. accept()
returns an SFTP instance in server mode (see the SFTP
documentation for details). info
has these properties:
shell(< mixed >accept, < mixed >reject) - The client has requested an interactive shell. accept
and reject
are functions if the client requested a response. accept()
returns a Channel for the interactive shell.
signal(< mixed >accept, < mixed >reject, < object >info) - The client has sent a signal. accept
and reject
are functions if the client requested a response. info
has these properties:
SIGUSR1
).subsystem(< mixed >accept, < mixed >reject, < object >info) - The client has requested an arbitrary subsystem. accept
and reject
are functions if the client requested a response. accept()
returns a Channel for the subsystem. info
has these properties:
window-change(< mixed >accept, < mixed >reject, < object >info) - The client reported a change in window dimensions during this session. accept
and reject
are functions if the client requested a response. info
has these properties:
cols - integer - The new number of columns for the client window.
height - integer - The new height of the client window in pixels.
rows - integer - The new number of rows for the client window.
width - integer - The new width of the client window in pixels.
x11(< mixed >accept, < mixed >reject, < object >info) - The client requested X11 forwarding. accept
and reject
are functions if the client requested a response. info
has these properties:
cookie - string - The X11 authentication cookie encoded in hexadecimal.
protocol - string - The name of the X11 authentication method used (e.g. MIT-MAGIC-COOKIE-1
).
screen - integer - The screen number to forward X11 connections for.
single - boolean - true
if only a single connection should be forwarded.
This is a normal streams2 Duplex Stream (used both by clients and servers), with the following changes:
A boolean property allowHalfOpen
exists and behaves similarly to the property of the same name for net.Socket
. When the stream's end() is called, if allowHalfOpen
is true
, only EOF will be sent (the server can still send data if they have not already sent EOF). The default value for this property is true
.
A close
event is emitted once the channel is completely closed on both the client and server.
Client-specific:
For exec():
An exit
event may (the SSH2 spec says it is optional) be emitted when the process finishes. If the process finished normally, the process's return value is passed to the exit
callback. If the process was interrupted by a signal, the following are passed to the exit
callback: null, < string >signalName, < boolean >didCoreDump, < string >description.
If there was an exit
event, the close
event will be passed the same arguments for convenience.
A stderr
property contains a Readable stream that represents output from stderr.
For exec() and shell():
The readable side represents stdout and the writable side represents stdin.
setWindow(< integer >rows, < integer >cols, < integer >height, < integer >width) - (void) - Lets the server know that the local terminal window has been resized. The meaning of these arguments are described in the 'Pseudo-TTY settings' section.
signal(< string >signalName) - (void) - Sends a POSIX signal to the current process on the server. Valid signal names are: 'ABRT', 'ALRM', 'FPE', 'HUP', 'ILL', 'INT', 'KILL', 'PIPE', 'QUIT', 'SEGV', 'TERM', 'USR1', and 'USR2'. Some server implementations may ignore this request if they do not support signals. Note: If you are trying to send SIGINT and you find signal()
doesn't work, try writing '\x03'
to the Channel stream instead.
Server-specific:
For exec-enabled channel instances there is an additional method available that may be called right before you close the channel. It has two different signatures:
exit(< integer >exitCode) - (void) - Sends an exit status code to the client.
exit(< string >signalName[, < boolean >coreDumped[, < string >errorMsg]]) - (void) - Sends an exit status code to the client.
For exec and shell-enabled channel instances, channel.stderr
is a writable stream.
cols - < integer > - Number of columns. Default: 80
height - < integer > - Height in pixels. Default: 480
modes - < object > - An object containing Terminal Modes as keys, with each value set to each mode argument. Default: null
rows - < integer > - Number of rows. Default: 24
term - < string > - The value to use for $TERM. Default: 'vt100'
width - < integer > - Width in pixels. Default: 640
rows
and cols
override width
and height
when rows
and cols
are non-zero.
Pixel dimensions refer to the drawable area of the window.
Zero dimension parameters are ignored.
Name | Description |
---|---|
CS7 | 7 bit mode. |
CS8 | 8 bit mode. |
ECHOCTL | Echo control characters as ^(Char). |
ECHO | Enable echoing. |
ECHOE | Visually erase chars. |
ECHOKE | Visual erase for line kill. |
ECHOK | Kill character discards current line. |
ECHONL | Echo NL even if ECHO is off. |
ICANON | Canonicalize input lines. |
ICRNL | Map CR to NL on input. |
IEXTEN | Enable extensions. |
IGNCR | Ignore CR on input. |
IGNPAR | The ignore parity flag. The parameter SHOULD be 0 if this flag is FALSE, and 1 if it is TRUE. |
IMAXBEL | Ring bell on input queue full. |
INLCR | Map NL into CR on input. |
INPCK | Enable checking of parity errors. |
ISIG | Enable signals INTR, QUIT, [D]SUSP. |
ISTRIP | Strip 8th bit off characters. |
IUCLC | Translate uppercase characters to lowercase. |
IXANY | Any char will restart after stop. |
IXOFF | Enable input flow control. |
IXON | Enable output flow control. |
NOFLSH | Don't flush after interrupt. |
OCRNL | Translate carriage return to newline (output). |
OLCUC | Convert lowercase to uppercase. |
ONLCR | Map NL to CR-NL. |
ONLRET | Newline performs a carriage return (output). |
ONOCR | Translate newline to carriage return-newline (output). |
OPOST | Enable output processing. |
PARENB | Parity enable. |
PARMRK | Mark parity and framing errors. |
PARODD | Odd parity, else even. |
PENDIN | Retype pending input. |
TOSTOP | Stop background jobs from output. |
TTY_OP_ISPEED | Specifies the input baud rate in bits per second. |
TTY_OP_OSPEED | Specifies the output baud rate in bits per second. |
VDISCARD | Toggles the flushing of terminal output. |
VDSUSP | Another suspend character. |
VEOF | End-of-file character (sends EOF from the terminal). |
VEOL2 | Additional end-of-line character. |
VEOL | End-of-line character in addition to carriage return and/or linefeed. |
VERASE | Erase the character to left of the cursor. |
VFLUSH | Character to flush output. |
VINTR | Interrupt character; 255 if none. Similarly for the other characters. Not all of these characters are supported on all systems. |
VKILL | Kill the current input line. |
VLNEXT | Enter the next character typed literally, even if it is a special character |
VQUIT | The quit character (sends SIGQUIT signal on POSIX systems). |
VREPRINT | Reprints the current input line. |
VSTART | Continues paused output (normally control-Q). |
VSTATUS | Prints system status line (load, command, pid, etc). |
VSTOP | Pauses output (normally control-S). |
VSUSP | Suspends the current program. |
VSWTCH | Switch to a different shell layer. |
VWERASE | Erases a word left of cursor. |
XCASE | Enable input and output of uppercase characters by preceding their lowercase equivalents with "". |
http.Agent
instance used to tunnel an HTTP connection over SSH. sshConfig
is what is passed to client.connect()
and agentOptions
is passed to the http.Agent
constructor.https.Agent
instance used to tunnel an HTTP connection over SSH. sshConfig
is what is passed to client.connect()
and agentOptions
is passed to the https.Agent
constructor.parseKey(< mixed >keyData[, < string >passphrase]) - mixed - Parses a private/public key in OpenSSH, RFC4716, or PPK format. For encrypted private keys, the key will be decrypted with the given passphrase
. keyData
can be a Buffer or string value containing the key contents. The returned value will be an array of objects (currently in the case of modern OpenSSH keys) or an object with these properties and methods:
comment - string - The comment for the key
equals(< mixed >otherKey) - boolean - This returns true
if otherKey
(a parsed or parseable key) is the same as this key. This method does not compare the keys' comments
getPrivatePEM() - string - This returns the PEM version of a private key
getPublicPEM() - string - This returns the PEM version of a public key (for either public key or derived from a private key)
getPublicSSH() - string - This returns the SSH version of a public key (for either public key or derived from a private key)
isPrivateKey() - boolean - This returns true
if the key is a private key or not
sign(< mixed >data) - mixed - This signs the given data
using this key and returns a Buffer containing the signature on success. On failure, an Error will be returned. data
can be anything accepted by node's sign.update()
.
type - string - The full key type (e.g. 'ssh-rsa'
)
verify(< mixed >data, < Buffer >signature) - mixed - This verifies a signature
of the given data
using this key and returns true
if the signature could be verified. On failure, either false
will be returned or an Error will be returned upon a more critical failure. data
can be anything accepted by node's verify.update()
.
sftp.OPEN_MODE - OPEN_MODE
sftp.STATUS_CODE - STATUS_CODE
sftp.flagsToString - flagsToString()
sftp.stringToFlags - stringToFlags()
identities(< opaque >request) - (Server mode only) The client has requested a list of public keys stored in the agent. Use failureReply()
or getIdentitiesReply()
to reply appropriately.
sign(< opaque >request, < mixed >pubKey, < Buffer >data, < object >options) - (Server mode only) The client has requested data
to be signed using the key identified by pubKey
. Use failureReply()
or signReply()
to reply appropriately. options
may contain any of:
'sha256'
or 'sha512'
for RSA keys.(constructor)(< boolean >isClient) - Creates and returns a new AgentProtocol instance. isClient
determines whether the instance operates in client or server mode.
failureReply(< opaque >request) - (void) - (Server mode only) Replies to the given request
with a failure response.
getIdentities(< function >callback) - (void) - (Client mode only) Requests a list of public keys from the agent. callback
is passed (err, keys)
where keys
is a possible array of public keys for authentication.
getIdentitiesReply(< opaque >request, < array >keys) - (void) - (Server mode only) Responds to a identities list request
with the given array of keys in keys
.
sign(< mixed >pubKey, < Buffer >data, < object >options, < function >callback) - (void) - (Client mode only) Requests that the agent sign data
using the key identified by pubKey
. pubKey
can be any parsed (using utils.parseKey()
) or parseable key value. callback
is passed (err, signature)
where signature
is a possible Buffer containing the signature for the data
. options
may contain any of:
'sha256'
or 'sha512'
for RSA keys.signReply(< opaque >request, < Buffer >signature) - (void) - (Server mode only) Responds to a sign request
with the given signature in signature
.
In order to create a custom agent, your class must:
Extend BaseAgent
Call super()
in its constructor
Implement at least the following methods:
getIdentities(< function >callback) - (void) - Passes (err, keys)
to callback
where keys
is a possible array of public keys for authentication.
sign(< mixed >pubKey, < Buffer >data, < object >options, < function >callback) - (void) - Signs data
using the key identified by pubKey
. pubKey
can be any parsed (using utils.parseKey()
) or parseable key value. callback
should be passed (err, signature)
where signature
is a possible Buffer containing the signature for the data
. options
may contain any of:
'sha256'
or 'sha512'
for RSA keys.Additionally your class may implement the following method in order to support agent forwarding on the client:
(err, stream)
to callback
where stream
is a possible Duplex stream to be used to communicate with your agent. You will probably want to utilize AgentProtocol
as agent forwarding is an OpenSSH feature, so the stream
needs to be able to transmit/receive OpenSSH agent protocol packets.Client
's agent
configuration option: if the platform is Windows and it's the value "pageant", it creates a PageantAgent
, otherwise if it's not a path to a Windows pipe it creates a CygwinAgent
. In all other cases, it creates an OpenSSHAgent
.socketPath
in a Cygwin environment.socketPath
.Author: mscdex
Source Code: https://github.com/mscdex/ssh2
License: MIT license
1661346988
🐬🧋 Fztea (flipperzero-tea)
A bubbletea-bubble and TUI to interact with your flipper zero.
The flipper will be automatically detected, if multiple flippers are connected, the first one will be used.
# using go directly
$ go install github.com/jon4hz/fztea@latest
# from aur (btw)
$ yay -S fztea-bin
# local pkg manager
## debian / ubuntu
$ dpkg -i fztea-v0.2.0-linux-amd64.deb
## rhel / fedora / suse
$ rpm -i fztea-v0.2.0-linux-amd64.rpm
## alpine
$ apk add --allow-untrusted fztea-v0.2.0-linux-amd64.apk
# windows & macOS
# -> I'm sure you'll figure something out. (No binaries for macOS due to crosscompilation errors)
# trying to autodetect that dolphin
$ fztea
# no flipper found automatically :(
$ fztea -p /dev/ttyACM0
fztea also allows you to start an ssh server, serving the flipper zero ui over a remote connection.
Why? - Why not!
# start the ssh server listening on localhost:2222 (default)
$ fztea server -l 127.0.0.1:2222
# connect to the server (from the same machine)
$ ssh localhost -p 2222
By default, fztea
doesn't require any authentication but you can specify an authorized_keys
file if you want to.
# use authorized_keys for authentication
$ fztea server -l 127.0.0.1:2222 -k ~/.ssh/authorized_keys
Key | Flipper Event | Keypress Type |
---|---|---|
w, ↑ | up | short |
d, → | right | short |
s, ↓ | down | short |
a, ← | left | short |
o, enter, space | ok | short |
b, back, esc | back | short |
W, shift + ↑ | up | long |
D, shift + → | right | long |
S, shift + ↓ | down | long |
A, shift + ← | left | long |
O | ok | long |
B | back | long |
Author: jon4hz
Source Code: https://github.com/jon4hz/fztea
License: MIT license
1661318820
Wordle, now over SSH.
Try it:
ssh clidle.duckdns.org -p 3000
Or, run it locally:
go install github.com/ajeetdsouza/clidle@latest
You have 6 attempts to guess the correct word. Each guess must be a valid 5 letter word.
After submitting a guess, the letters will turn green, yellow, or gray.
Your final score is based on how many guesses it took to arrive at the solution:
Guesses | Score |
---|---|
1 | 100 |
2 | 90 |
3 | 80 |
4 | 70 |
5 | 60 |
6 | 50 |
Author: Ajeetdsouza
Source Code: https://github.com/ajeetdsouza/clidle
License: MIT license
1659831060
Step Certificates
step-ca
is an online certificate authority for secure, automated certificate management. It's the server counterpart to the step
CLI tool.
You can use it to:
Whatever your use case, step-ca
is easy to use and hard to misuse, thanks to safe, sane defaults.
Don't want to run your own CA? To get up and running quickly, or as an alternative to running your own step-ca
server, consider creating a free hosted smallstep Certificate Manager authority.
Setting up a public key infrastructure (PKI) is out of reach for many small teams. step-ca
makes it easier.
There are several ways to authorize a request with the CA and establish a chain of trust that suits your flow.
You can issue certificates in exchange for:
ACME is the protocol used by Let's Encrypt to automate the issuance of HTTPS certificates. It's super easy to issue certificates to any ACMEv2 (RFC8555) client.
Use ACME in development & pre-production
Supports the most popular ACME challenge types:
http-01
, place a token at a well-known URL to prove that you control the web serverdns-01
, add a TXT
record to prove that you control the DNS record settls-alpn-01
, respond to the challenge at the TLS layer (as Caddy does) to prove that you control the web serverWorks with any ACME client. We've written examples for:
Get certificates programmatically using ACME, using these libraries:
lego
for Golang (example usage)acme
module for Python (example usage)acme-client
for Node.js (example usage)Our own step
CLI tool is also an ACME client!
See our ACME tutorial for more
step-ca
by using SSH certificates instead of public keys and authorized_keys
filesstep
CLI integrationstep-ca
step-ca
See our installation docs here.
Documentation can be found in a handful of different places:
On the web at https://smallstep.com/docs/step-ca.
On the command line with step help ca xxx
where xxx
is the subcommand you are interested in. Ex: step help ca provisioner list
.
In your browser, by running step help --http=:8080 ca
from the command line and visiting http://localhost:8080.
The docs folder is being deprecated, but it still has some documentation and tutorials.
Questions? Find us in Discussions or Join our Discord.
Website | Documentation | Installation | Getting Started | Contributor's Guide
Author: Smallstep
Source Code: https://github.com/smallstep/certificates
License: Apache-2.0 license
1657952100
encrypt messages based on ssh public keys
It can be frustrating and annoying to communicate with somebody using public key cryptography since setting up PGP/GPG is a hassle, particularly managing keyrings and webs of trust.
Luckily, you can fetch the public ssh keys of anybody on github by going to:
https://github.com/$USERNAME.keys
If you just want to send somebody an encrypted message out of the blue and they already have a github account with RSA keys uploaded to it, you can just do:
cipherhub $USERNAME < secret_message.txt
and it will fetch their public keys from github, storing the key locally for next time.
There is an openssl rsautl
command to do this but the usage is not particularly friendly and doesn't keep a keyring around.
install
With npm do:
npm install -g cipherhub
to get the cipherhub
command.
usage
cipherhub USERNAME {OPTIONS} < message.txt
Create an encrypted message for USERNAME on stdin.
If there isn't yet a local key stored for USERNAME, request a key from
https://github.com/$USERNAME.keys
If there are multiple RSA keys, the operation fails and you will need to
add the key you want manually with `cipherhub --add`.
If there are no RSA keys, the command fails with a nonzero exit code.
OPTIONS are:
--no-github don't request key data from github, just fail
--no-save don't automatically save keys fetched from github
--quiet, -q suppress extra output
--encoding, -e output encoding to use. default: base64
cipherhub --add USERNAME < id_rsa.pub
cipherhub -a USERNAME < id_rsa.pub
Set the public key for USERNAME from stdin.
cipherhub --remove USERNAME
cipherhub -r USERNAME
Remove a USERNAME from the local key list.
cipherhub --list
cipherhub -l
List all the keys in the local key list.
cipherhub --decrypt PRIVKEY {OPTIONS}
cipherhub -d PRIVKEY {OPTIONS}
Decrypt a message on stdin with an rsa key file PRIVKEY.
If PRIVKEY isn't specified, only `-d` by itself, cipherhub uses ~/.ssh/id_rsa
OPTIONS are:
--encoding, -e input encoding. default: base64
crazy ideas
You can create private github issues by just encrypting your message with the maintainer's public key and posting the issue with the ciphertext.
caveat npmtor
github's servers can be compromised by a court order, intruder, or employee. You should use a secondary means of verification to check all the keys fetched from github where secrecy from courts, intruders, and github employees is of paramount importance.
Author: Substack
Source Code: https://github.com/substack/cipherhub
License: View license
1655173693
Description
SSH2 client and server modules written in pure JavaScript for node.js.
Development/testing is done against OpenSSH (8.7 currently).
Changes (breaking or otherwise) in v1.0.0 can be found here.
cpu-features
is set as an optional package dependency (you do not need to install it explicitly/separately from ssh2
) that will be automatically built and used if possible. See the project's documentation for its own requirements.npm install ssh2
const { readFileSync } = require('fs');
const { Client } = require('ssh2');
const conn = new Client();
conn.on('ready', () => {
console.log('Client :: ready');
conn.exec('uptime', (err, stream) => {
if (err) throw err;
stream.on('close', (code, signal) => {
console.log('Stream :: close :: code: ' + code + ', signal: ' + signal);
conn.end();
}).on('data', (data) => {
console.log('STDOUT: ' + data);
}).stderr.on('data', (data) => {
console.log('STDERR: ' + data);
});
});
}).connect({
host: '192.168.100.100',
port: 22,
username: 'frylock',
privateKey: readFileSync('/path/to/my/key')
});
// example output:
// Client :: ready
// STDOUT: 17:41:15 up 22 days, 18:09, 1 user, load average: 0.00, 0.01, 0.05
//
// Stream :: exit :: code: 0, signal: undefined
// Stream :: close
const { readFileSync } = require('fs');
const { Client } = require('ssh2');
const conn = new Client();
conn.on('ready', () => {
console.log('Client :: ready');
conn.shell((err, stream) => {
if (err) throw err;
stream.on('close', () => {
console.log('Stream :: close');
conn.end();
}).on('data', (data) => {
console.log('OUTPUT: ' + data);
});
stream.end('ls -l\nexit\n');
});
}).connect({
host: '192.168.100.100',
port: 22,
username: 'frylock',
privateKey: readFileSync('/path/to/my/key')
});
// example output:
// Client :: ready
// STDOUT: Last login: Sun Jun 15 09:37:21 2014 from 192.168.100.100
//
// STDOUT: ls -l
// exit
//
// STDOUT: frylock@athf:~$ ls -l
//
// STDOUT: total 8
//
// STDOUT: drwxr-xr-x 2 frylock frylock 4096 Nov 18 2012 mydir
//
// STDOUT: -rw-r--r-- 1 frylock frylock 25 Apr 11 2013 test.txt
//
// STDOUT: frylock@athf:~$ exit
//
// STDOUT: logout
//
// Stream :: close
const { Client } = require('ssh2');
const conn = new Client();
conn.on('ready', () => {
console.log('Client :: ready');
conn.forwardOut('192.168.100.102', 8000, '127.0.0.1', 80, (err, stream) => {
if (err) throw err;
stream.on('close', () => {
console.log('TCP :: CLOSED');
conn.end();
}).on('data', (data) => {
console.log('TCP :: DATA: ' + data);
}).end([
'HEAD / HTTP/1.1',
'User-Agent: curl/7.27.0',
'Host: 127.0.0.1',
'Accept: */*',
'Connection: close',
'',
''
].join('\r\n'));
});
}).connect({
host: '192.168.100.100',
port: 22,
username: 'frylock',
password: 'nodejsrules'
});
// example output:
// Client :: ready
// TCP :: DATA: HTTP/1.1 200 OK
// Date: Thu, 15 Nov 2012 13:52:58 GMT
// Server: Apache/2.2.22 (Ubuntu)
// X-Powered-By: PHP/5.4.6-1ubuntu1
// Last-Modified: Thu, 01 Jan 1970 00:00:00 GMT
// Content-Encoding: gzip
// Vary: Accept-Encoding
// Connection: close
// Content-Type: text/html; charset=UTF-8
//
//
// TCP :: CLOSED
const { Client } = require('ssh2');
const conn = new Client();
conn.on('ready', () => {
console.log('Client :: ready');
conn.forwardIn('127.0.0.1', 8000, (err) => {
if (err) throw err;
console.log('Listening for connections on server on port 8000!');
});
}).on('tcp connection', (info, accept, reject) => {
console.log('TCP :: INCOMING CONNECTION:');
console.dir(info);
accept().on('close', () => {
console.log('TCP :: CLOSED');
}).on('data', (data) => {
console.log('TCP :: DATA: ' + data);
}).end([
'HTTP/1.1 404 Not Found',
'Date: Thu, 15 Nov 2012 02:07:58 GMT',
'Server: ForwardedConnection',
'Content-Length: 0',
'Connection: close',
'',
''
].join('\r\n'));
}).connect({
host: '192.168.100.100',
port: 22,
username: 'frylock',
password: 'nodejsrules'
});
// example output:
// Client :: ready
// Listening for connections on server on port 8000!
// (.... then from another terminal on the server: `curl -I http://127.0.0.1:8000`)
// TCP :: INCOMING CONNECTION: { destIP: '127.0.0.1',
// destPort: 8000,
// srcIP: '127.0.0.1',
// srcPort: 41969 }
// TCP DATA: HEAD / HTTP/1.1
// User-Agent: curl/7.27.0
// Host: 127.0.0.1:8000
// Accept: */*
//
//
// TCP :: CLOSED
const { Client } = require('ssh2');
const conn = new Client();
conn.on('ready', () => {
console.log('Client :: ready');
conn.sftp((err, sftp) => {
if (err) throw err;
sftp.readdir('foo', (err, list) => {
if (err) throw err;
console.dir(list);
conn.end();
});
});
}).connect({
host: '192.168.100.100',
port: 22,
username: 'frylock',
password: 'nodejsrules'
});
// example output:
// Client :: ready
// [ { filename: 'test.txt',
// longname: '-rw-r--r-- 1 frylock frylock 12 Nov 18 11:05 test.txt',
// attrs:
// { size: 12,
// uid: 1000,
// gid: 1000,
// mode: 33188,
// atime: 1353254750,
// mtime: 1353254744 } },
// { filename: 'mydir',
// longname: 'drwxr-xr-x 2 frylock frylock 4096 Nov 18 15:03 mydir',
// attrs:
// { size: 1048576,
// uid: 1000,
// gid: 1000,
// mode: 16877,
// atime: 1353269007,
// mtime: 1353269007 } } ]
const { Client } = require('ssh2');
const conn1 = new Client();
const conn2 = new Client();
// Checks uptime on 10.1.1.40 via 192.168.1.1
conn1.on('ready', () => {
console.log('FIRST :: connection ready');
// Alternatively, you could use something like netcat or socat with exec()
// instead of forwardOut(), depending on what the server allows
conn1.forwardOut('127.0.0.1', 12345, '10.1.1.40', 22, (err, stream) => {
if (err) {
console.log('FIRST :: forwardOut error: ' + err);
return conn1.end();
}
conn2.connect({
sock: stream,
username: 'user2',
password: 'password2',
});
});
}).connect({
host: '192.168.1.1',
username: 'user1',
password: 'password1',
});
conn2.on('ready', () => {
// This connection is the one to 10.1.1.40
console.log('SECOND :: connection ready');
conn2.exec('uptime', (err, stream) => {
if (err) {
console.log('SECOND :: exec error: ' + err);
return conn1.end();
}
stream.on('close', () => {
conn1.end(); // close parent (and this) connection
}).on('data', (data) => {
console.log(data.toString());
});
});
});
const { Socket } = require('net');
const { Client } = require('ssh2');
const conn = new Client();
conn.on('x11', (info, accept, reject) => {
const xserversock = new net.Socket();
xserversock.on('connect', () => {
const xclientsock = accept();
xclientsock.pipe(xserversock).pipe(xclientsock);
});
// connects to localhost:0.0
xserversock.connect(6000, 'localhost');
});
conn.on('ready', () => {
conn.exec('xeyes', { x11: true }, (err, stream) => {
if (err) throw err;
let code = 0;
stream.on('close', () => {
if (code !== 0)
console.log('Do you have X11 forwarding enabled on your SSH server?');
conn.end();
}).on('exit', (exitcode) => {
code = exitcode;
});
});
}).connect({
host: '192.168.1.1',
username: 'foo',
password: 'bar'
});
const socks = require('socksv5');
const { Client } = require('ssh2');
const sshConfig = {
host: '192.168.100.1',
port: 22,
username: 'nodejs',
password: 'rules'
};
socks.createServer((info, accept, deny) => {
// NOTE: you could just use one ssh2 client connection for all forwards, but
// you could run into server-imposed limits if you have too many forwards open
// at any given time
const conn = new Client();
conn.on('ready', () => {
conn.forwardOut(info.srcAddr,
info.srcPort,
info.dstAddr,
info.dstPort,
(err, stream) => {
if (err) {
conn.end();
return deny();
}
const clientSocket = accept(true);
if (clientSocket) {
stream.pipe(clientSocket).pipe(stream).on('close', () => {
conn.end();
});
} else {
conn.end();
}
});
}).on('error', (err) => {
deny();
}).connect(sshConfig);
}).listen(1080, 'localhost', () => {
console.log('SOCKSv5 proxy server started on port 1080');
}).useAuth(socks.auth.None());
// test with cURL:
// curl -i --socks5 localhost:1080 google.com
const http = require('http');
const { Client, HTTPAgent, HTTPSAgent } = require('ssh2');
const sshConfig = {
host: '192.168.100.1',
port: 22,
username: 'nodejs',
password: 'rules'
};
// Use `HTTPSAgent` instead for an HTTPS request
const agent = new HTTPAgent(sshConfig);
http.get({
host: '192.168.200.1',
agent,
headers: { Connection: 'close' }
}, (res) => {
console.log(res.statusCode);
console.dir(res.headers);
res.resume();
});
const { Client } = require('ssh2');
const xmlhello = `
<?xml version="1.0" encoding="UTF-8"?>
<hello xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<capabilities>
<capability>urn:ietf:params:netconf:base:1.0</capability>
</capabilities>
</hello>]]>]]>`;
const conn = new Client();
conn.on('ready', () => {
console.log('Client :: ready');
conn.subsys('netconf', (err, stream) => {
if (err) throw err;
stream.on('data', (data) => {
console.log(data);
}).write(xmlhello);
});
}).connect({
host: '1.2.3.4',
port: 22,
username: 'blargh',
password: 'honk'
});
const { timingSafeEqual } = require('crypto');
const { readFileSync } = require('fs');
const { inspect } = require('util');
const { utils: { parseKey }, Server } = require('ssh2');
const allowedUser = Buffer.from('foo');
const allowedPassword = Buffer.from('bar');
const allowedPubKey = parseKey(readFileSync('foo.pub'));
function checkValue(input, allowed) {
const autoReject = (input.length !== allowed.length);
if (autoReject) {
// Prevent leaking length information by always making a comparison with the
// same input when lengths don't match what we expect ...
allowed = input;
}
const isMatch = timingSafeEqual(input, allowed);
return (!autoReject && isMatch);
}
new Server({
hostKeys: [readFileSync('host.key')]
}, (client) => {
console.log('Client connected!');
client.on('authentication', (ctx) => {
let allowed = true;
if (!checkValue(Buffer.from(ctx.username), allowedUser))
allowed = false;
switch (ctx.method) {
case 'password':
if (!checkValue(Buffer.from(ctx.password), allowedPassword))
return ctx.reject();
break;
case 'publickey':
if (ctx.key.algo !== allowedPubKey.type
|| !checkValue(ctx.key.data, allowedPubKey.getPublicSSH())
|| (ctx.signature && allowedPubKey.verify(ctx.blob, ctx.signature) !== true)) {
return ctx.reject();
}
break;
default:
return ctx.reject();
}
if (allowed)
ctx.accept();
else
ctx.reject();
}).on('ready', () => {
console.log('Client authenticated!');
client.on('session', (accept, reject) => {
const session = accept();
session.once('exec', (accept, reject, info) => {
console.log('Client wants to execute: ' + inspect(info.command));
const stream = accept();
stream.stderr.write('Oh no, the dreaded errors!\n');
stream.write('Just kidding about the errors!\n');
stream.exit(0);
stream.end();
});
});
}).on('close', () => {
console.log('Client disconnected');
});
}).listen(0, '127.0.0.1', function() {
console.log('Listening on port ' + this.address().port);
});
const { timingSafeEqual } = require('crypto');
const { readFileSync } = require('fs');
const { inspect } = require('util');
const {
Server,
sftp: {
OPEN_MODE,
STATUS_CODE,
},
} = require('ssh2');
const allowedUser = Buffer.from('foo');
const allowedPassword = Buffer.from('bar');
function checkValue(input, allowed) {
const autoReject = (input.length !== allowed.length);
if (autoReject) {
// Prevent leaking length information by always making a comparison with the
// same input when lengths don't match what we expect ...
allowed = input;
}
const isMatch = timingSafeEqual(input, allowed);
return (!autoReject && isMatch);
}
// This simple SFTP server implements file uploading where the contents get
// ignored ...
new ssh2.Server({
hostKeys: [readFileSync('host.key')]
}, (client) => {
console.log('Client connected!');
client.on('authentication', (ctx) => {
let allowed = true;
if (!checkValue(Buffer.from(ctx.username), allowedUser))
allowed = false;
switch (ctx.method) {
case 'password':
if (!checkValue(Buffer.from(ctx.password), allowedPassword))
return ctx.reject();
break;
default:
return ctx.reject();
}
if (allowed)
ctx.accept();
else
ctx.reject();
}).on('ready', () => {
console.log('Client authenticated!');
client.on('session', (accept, reject) => {
const session = accept();
session.on('sftp', (accept, reject) => {
console.log('Client SFTP session');
const openFiles = new Map();
let handleCount = 0;
const sftp = accept();
sftp.on('OPEN', (reqid, filename, flags, attrs) => {
// Only allow opening /tmp/foo.txt for writing
if (filename !== '/tmp/foo.txt' || !(flags & OPEN_MODE.WRITE))
return sftp.status(reqid, STATUS_CODE.FAILURE);
// Create a fake handle to return to the client, this could easily
// be a real file descriptor number for example if actually opening
// a file on disk
const handle = Buffer.alloc(4);
openFiles.set(handleCount, true);
handle.writeUInt32BE(handleCount++, 0);
console.log('Opening file for write')
sftp.handle(reqid, handle);
}).on('WRITE', (reqid, handle, offset, data) => {
if (handle.length !== 4
|| !openFiles.has(handle.readUInt32BE(0))) {
return sftp.status(reqid, STATUS_CODE.FAILURE);
}
// Fake the write operation
sftp.status(reqid, STATUS_CODE.OK);
console.log('Write to file at offset ${offset}: ${inspect(data)}');
}).on('CLOSE', (reqid, handle) => {
let fnum;
if (handle.length !== 4
|| !openFiles.has(fnum = handle.readUInt32BE(0))) {
return sftp.status(reqid, STATUS_CODE.FAILURE);
}
console.log('Closing file');
openFiles.delete(fnum);
sftp.status(reqid, STATUS_CODE.OK);
});
});
});
}).on('close', () => {
console.log('Client disconnected');
});
}).listen(0, '127.0.0.1', function() {
console.log('Listening on port ' + this.address().port);
});
You can find more examples in the examples
directory of this repository.
require('ssh2').Client
is the Client constructor.
require('ssh2').Server
is the Server constructor.
require('ssh2').utils
is an object containing some useful utilities.
require('ssh2').HTTPAgent
is an http.Agent
constructor.
require('ssh2').HTTPSAgent
is an https.Agent
constructor. Its API is the same as HTTPAgent
except it's for HTTPS connections.
require('ssh2').AgentProtocol
is a Duplex stream class that aids in communicating over the OpenSSH agent protocol.
require('ssh2').BaseAgent
is a base class for creating custom authentication agents.
require('ssh2').createAgent
is a helper function that creates a new agent instance using the same logic as the agent
configuration option: if the platform is Windows and it's the value "pageant", it creates a PageantAgent
, otherwise if it's not a path to a Windows pipe it creates a CygwinAgent
. In all other cases, it creates an OpenSSHAgent
.
require('ssh2').CygwinAgent
is an agent class implementation that communicates with agents in a Cygwin environment.
require('ssh2').OpenSSHAgent
is an agent class implementation that communicates with OpenSSH agents over a UNIX socket.
require('ssh2').PageantAgent
is an agent class implementation that communicates with Pageant agent processes.
banner(< string >message, < string >language) - A notice was sent by the server upon connection.
change password(< string >prompt, < function >done) - If using password-based user authentication, the server has requested that the user's password be changed. Call done
with the new password.
close() - The socket was closed.
end() - The socket was disconnected.
error(< Error >err) - An error occurred. A 'level' property indicates 'client-socket' for socket-level errors and 'client-ssh' for SSH disconnection messages. In the case of 'client-ssh' messages, there may be a 'description' property that provides more detail.
handshake(< object >negotiated) - Emitted when a handshake has completed (either initial or rekey). negotiated
contains the negotiated details of the handshake and is of the form:
// In this particular case `mac` is empty because there is no separate MAC
// because it's integrated into AES in GCM mode
{ kex: 'ecdh-sha2-nistp256',
srvHostKey: 'rsa-sha2-512',
cs: { // Client to server algorithms
cipher: 'aes128-gcm',
mac: '',
compress: 'none',
lang: ''
},
sc: { // Server to client algorithms
cipher: 'aes128-gcm',
mac: '',
compress: 'none',
lang: ''
}
}
hostkeys(< array >keys) - Emitted when the server announces its available host keys. keys
is the list of parsed (using parseKey()
) host public keys.
keyboard-interactive(< string >name, < string >instructions, < string >instructionsLang, < array >prompts, < function >finish) - The server is asking for replies to the given prompts
for keyboard-interactive user authentication. name
is generally what you'd use as a window title (for GUI apps). prompts
is an array of { prompt: 'Password: ', echo: false }
style objects (here echo
indicates whether user input should be displayed on the screen). The answers for all prompts must be provided as an array of strings and passed to finish
when you are ready to continue. Note: It's possible for the server to come back and ask more questions.
ready() - Authentication was successful.
rekey() - Emitted when a rekeying operation has completed (either client or server-initiated).
tcp connection(< object >details, < function >accept, < function >reject) - An incoming forwarded TCP connection is being requested. Calling accept
accepts the connection and returns a Channel
object. Calling reject
rejects the connection and no further action is needed. details
contains:
destIP - string - The remote IP the connection was received on (given in earlier call to forwardIn()
).
destPort - integer - The remote port the connection was received on (given in earlier call to forwardIn()
).
srcIP - string - The originating IP of the connection.
srcPort - integer - The originating port of the connection.
unix connection(< object >details, < function >accept, < function >reject) - An incoming forwarded UNIX socket connection is being requested. Calling accept
accepts the connection and returns a Channel
object. Calling reject
rejects the connection and no further action is needed. details
contains:
x11(< object >details, < function >accept, < function >reject) - An incoming X11 connection is being requested. Calling accept
accepts the connection and returns a Channel
object. Calling reject
rejects the connection and no further action is needed. details
contains:
srcIP - string - The originating IP of the connection.
srcPort - integer - The originating port of the connection.
(constructor)() - Creates and returns a new Client instance.
connect(< object >config) - (void) - Attempts a connection to a server using the information given in config
:
agent - string - Path to ssh-agent's UNIX socket for ssh-agent-based user authentication. Windows users: set to 'pageant' for authenticating with Pageant or (actual) path to a cygwin "UNIX socket." Default: (none)
agentForward - boolean - Set to true
to use OpenSSH agent forwarding (auth-agent@openssh.com
) for the life of the connection. agent
must also be set to use this feature. Default: false
algorithms - object - This option allows you to explicitly override the default transport layer algorithms used for the connection. The value for each category must either be an array of valid algorithm names to set an exact list (with the most preferable first) or an object containing append
, prepend
, and/or remove
properties that each contain an array of algorithm names or RegExps to match to adjust default lists for each category. Valid keys:
cipher - mixed - Ciphers.
chacha20-poly1305@openssh.com
(priority of chacha20-poly1305 may vary depending upon CPU and/or optional binding availability)aes128-gcm
aes128-gcm@openssh.com
aes256-gcm
aes256-gcm@openssh.com
aes128-ctr
aes192-ctr
aes256-ctr
3des-cbc
aes256-cbc
aes192-cbc
aes128-cbc
arcfour256
arcfour128
arcfour
blowfish-cbc
cast128-cbc
compress - mixed - Compression algorithms.
none
zlib@openssh.com
zlib
hmac - mixed - (H)MAC algorithms.
hmac-sha2-256-etm@openssh.com
hmac-sha2-512-etm@openssh.com
hmac-sha1-etm@openssh.com
hmac-sha2-256
hmac-sha2-512
hmac-sha1
hmac-md5
hmac-sha2-256-96
hmac-sha2-512-96
hmac-ripemd160
hmac-sha1-96
hmac-md5-96
kex - mixed - Key exchange algorithms.
curve25519-sha256
(node v14.0.0+)curve25519-sha256@libssh.org
(node v14.0.0+)ecdh-sha2-nistp256
ecdh-sha2-nistp384
ecdh-sha2-nistp521
diffie-hellman-group-exchange-sha256
diffie-hellman-group14-sha256
diffie-hellman-group15-sha512
diffie-hellman-group16-sha512
diffie-hellman-group17-sha512
diffie-hellman-group18-sha512
diffie-hellman-group-exchange-sha1
diffie-hellman-group14-sha1
diffie-hellman-group1-sha1
serverHostKey - mixed - Server host key formats.
ssh-ed25519
(node v12.0.0+)ecdsa-sha2-nistp256
ecdsa-sha2-nistp384
ecdsa-sha2-nistp521
rsa-sha2-512
rsa-sha2-256
ssh-rsa
ssh-dss
authHandler - mixed - Must be an array of objects as described below, an array of strings containing valid authentication method names (username and credentials are pulled from the object passed to connect()
), or a function with parameters (methodsLeft, partialSuccess, callback)
where methodsLeft
and partialSuccess
are null
on the first authentication attempt, otherwise are an array and boolean respectively. Return or call callback()
with either the name of the authentication method or an object containing the method name along with method-specific details to try next (return/pass false
to signal no more methods to try). Valid method names are: 'none', 'password', 'publickey', 'agent', 'keyboard-interactive', 'hostbased'
. Default: function that follows a set method order: None -> Password -> Private Key -> Agent (-> keyboard-interactive if tryKeyboard
is true
) -> Hostbased
When returning or calling callback()
with an object, it can take one of the following forms:
{
type: 'none',
username: 'foo',
}
{
type: 'password'
username: 'foo',
password: 'bar',
}
{
type: 'publickey'
username: 'foo',
// Can be a string, Buffer, or parsed key containing a private key
key: ...,
// `passphrase` only required for encrypted keys
passphrase: ...,
}
{
type: 'hostbased'
username: 'foo',
localHostname: 'baz',
localUsername: 'quux',
// Can be a string, Buffer, or parsed key containing a private key
key: ...,
// `passphrase` only required for encrypted keys
passphrase: ...,
}
{
type: 'agent'
username: 'foo',
// Can be a string that is interpreted exactly like the `agent`
// connection config option or can be a custom agent
// object/instance that extends and implements `BaseAgent`
agent: ...,
}
{
type: 'keyboard-interactive'
username: 'foo',
// This works exactly the same way as a 'keyboard-interactive'
// Client event handler
prompt: (name, instructions, instructionsLang, prompts, finish) => {
// ...
},
}
debug - function - Set this to a function that receives a single string argument to get detailed (local) debug information. Default: (none)
forceIPv4 - boolean - Only connect via resolved IPv4 address for host
. Default: false
forceIPv6 - boolean - Only connect via resolved IPv6 address for host
. Default: false
host - string - Hostname or IP address of the server. Default: 'localhost'
hostHash - string - Any valid hash algorithm supported by node. The host's key is hashed using this algorithm and passed to the hostVerifier function as a hex string. Default: (none)
hostVerifier - function - Function with parameters (hashedKey[, callback])
where hashedKey
is a string hex hash of the host's key for verification purposes. Return true
to continue with the handshake or false
to reject and disconnect, or call callback()
with true
or false
if you need to perform asynchronous verification. Default: (auto-accept if hostVerifier
is not set)
keepaliveCountMax - integer - How many consecutive, unanswered SSH-level keepalive packets that can be sent to the server before disconnection (similar to OpenSSH's ServerAliveCountMax config option). Default: 3
keepaliveInterval - integer - How often (in milliseconds) to send SSH-level keepalive packets to the server (in a similar way as OpenSSH's ServerAliveInterval config option). Set to 0 to disable. Default: 0
localAddress - string - IP address of the network interface to use to connect to the server. Default: (none -- determined by OS)
localHostname - string - Along with localUsername and privateKey, set this to a non-empty string for hostbased user authentication. Default: (none)
localPort - string - The local port number to connect from. Default: (none -- determined by OS)
localUsername - string - Along with localHostname and privateKey, set this to a non-empty string for hostbased user authentication. Default: (none)
passphrase - string - For an encrypted privateKey
, this is the passphrase used to decrypt it. Default: (none)
password - string - Password for password-based user authentication. Default: (none)
port - integer - Port number of the server. Default: 22
privateKey - mixed - Buffer or string that contains a private key for either key-based or hostbased user authentication (OpenSSH format). Default: (none)
readyTimeout - integer - How long (in milliseconds) to wait for the SSH handshake to complete. Default: 20000
sock - ReadableStream - A ReadableStream to use for communicating with the server instead of creating and using a new TCP connection (useful for connection hopping).
strictVendor - boolean - Performs a strict server vendor check before sending vendor-specific requests, etc. (e.g. check for OpenSSH server when using openssh_noMoreSessions()
) Default: true
tryKeyboard - boolean - Try keyboard-interactive user authentication if primary user authentication method fails. If you set this to true
, you need to handle the keyboard-interactive
event. Default: false
username - string - Username for authentication. Default: (none)
end() - (void) - Disconnects the socket.
exec(< string >command[, < object >options], < function >callback) - (void) - Executes command
on the server. callback
has 2 parameters: < Error >err, < Channel >stream. Valid options
properties are:
env - object - An environment to use for the execution of the command.
pty - mixed - 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).
x11 - mixed - Set to true
to use defaults below, set to a number to specify a specific screen number, or an object with the following valid properties:
cookie - mixed - The authentication cookie. Can be a hex string or a Buffer containing the raw cookie value (which will be converted to a hex string). Default: (random 16 byte value)
protocol - string - The authentication protocol name. Default: 'MIT-MAGIC-COOKIE-1'
screen - number - Screen number to use Default: 0
single - boolean - Allow just a single connection? Default: false
forwardIn(< string >remoteAddr, < integer >remotePort, < function >callback) - (void) - Bind to remoteAddr
on remotePort
on the server and forward incoming TCP connections. callback
has 2 parameters: < Error >err, < integer >port (port
is the assigned port number if remotePort
was 0). Here are some special values for remoteAddr
and their associated binding behaviors:
'' - Connections are to be accepted on all protocol families supported by the server.
'0.0.0.0' - Listen on all IPv4 addresses.
'::' - Listen on all IPv6 addresses.
'localhost' - Listen on all protocol families supported by the server on loopback addresses only.
'127.0.0.1' and '::1' - Listen on the loopback interfaces for IPv4 and IPv6, respectively.
forwardOut(< string >srcIP, < integer >srcPort, < string >dstIP, < integer >dstPort, < function >callback) - (void) - Open a connection with srcIP
and srcPort
as the originating address and port and dstIP
and dstPort
as the remote destination address and port. callback
has 2 parameters: < Error >err, < Channel >stream.
openssh_forwardInStreamLocal(< string >socketPath, < function >callback) - (void) - OpenSSH extension that binds to a UNIX domain socket at socketPath
on the server and forwards incoming connections. callback
has 1 parameter: < Error >err.
openssh_forwardOutStreamLocal(< string >socketPath, < function >callback) - (void) - OpenSSH extension that opens a connection to a UNIX domain socket at socketPath
on the server. callback
has 2 parameters: < Error >err, < Channel >stream.
openssh_noMoreSessions(< function >callback) - (void) - OpenSSH extension that sends a request to reject any new sessions (e.g. exec, shell, sftp, subsys) for this connection. callback
has 1 parameter: < Error >err.
openssh_unforwardInStreamLocal(< string >socketPath, < function >callback) - (void) - OpenSSH extension that unbinds from a UNIX domain socket at socketPath
on the server and stops forwarding incoming connections. callback
has 1 parameter: < Error >err.
rekey([< function >callback]) - (void) - Initiates a rekey with the server. If callback
is supplied, it is added as a one-time handler for the rekey
event.
sftp(< function >callback) - (void) - Starts an SFTP session. callback
has 2 parameters: < Error >err, < SFTP >sftp. For methods available on sftp
, see the SFTP
client documentation.
shell([[< mixed >window,] < object >options]< function >callback) - (void) - Starts an interactive shell session on the server, with an optional window
object containing pseudo-tty settings (see 'Pseudo-TTY settings'). If window === false
, then no pseudo-tty is allocated. options
supports the x11
and env
options as described in exec()
. callback
has 2 parameters: < Error >err, < Channel >stream.
subsys(< string >subsystem, < function >callback) - (void) - Invokes subsystem
on the server. callback
has 2 parameters: < Error >err, < Channel >stream.
unforwardIn(< string >remoteAddr, < integer >remotePort, < function >callback) - (void) - Unbind from remoteAddr
on remotePort
on the server and stop forwarding incoming TCP connections. Until callback
is called, more connections may still come in. callback
has 1 parameter: < Error >err.
connection(< Connection >client, < object >info) - A new client has connected. info
contains the following properties:
family - string - The remoteFamily
of the connection.
header - object - Information about the client's header:
identRaw - string - The raw client identification string.
versions - object - Various version information:
protocol - string - The SSH protocol version (always 1.99
or 2.0
).
software - string - The software name and version of the client.
comments - string - Any text that comes after the software name/version.
{ identRaw: 'SSH-2.0-OpenSSH_6.6.1p1 Ubuntu-2ubuntu2',
version: {
protocol: '2.0',
software: 'OpenSSH_6.6.1p1'
},
comments: 'Ubuntu-2ubuntu2' }
* **ip** - _string_ - The `remoteAddress` of the connection.
* **port** - _integer_ - The `remotePort` of the connection.
(constructor)(< object >config[, < function >connectionListener]) - Creates and returns a new Server instance. Server instances also have the same methods/properties/events as net.Server
. connectionListener
if supplied, is added as a connection
listener. Valid config
properties:
algorithms - object - This option allows you to explicitly override the default transport layer algorithms used for incoming client connections. Each value must be an array of valid algorithms for that category. The order of the algorithms in the arrays are important, with the most favorable being first. For a list of valid and default algorithm names, please review the documentation for the version of ssh2
used by this module. Valid keys:
cipher - array - Ciphers.
compress - array - Compression algorithms.
hmac - array - (H)MAC algorithms.
kex - array - Key exchange algorithms.
serverHostKey - array - Server host key formats.
banner - string - A message that is sent to clients once, right before authentication begins. Default: (none)
debug - function - Set this to a function that receives a single string argument to get detailed (local) debug information. Default: (none)
greeting - string - A message that is sent to clients immediately upon connection, before handshaking begins. Note: Most clients usually ignore this. Default: (none)
highWaterMark - integer - This is the highWaterMark
to use for the parser stream. Default: 32 * 1024
hostKeys - array - An array of either Buffers/strings that contain host private keys or objects in the format of { key: <Buffer/string>, passphrase: <string> }
for encrypted private keys. (Required) Default: (none)
ident - string - A custom server software name/version identifier. Default: 'ssh2js' + moduleVersion + 'srv'
injectSocket(< DuplexStream >socket) - Injects a bidirectional stream as though it were a TCP socket connection. Additionally, socket
should include net.Socket
-like properties to ensure the best compatibility (e.g. socket.remoteAddress
, socket.remotePort
, socket.remoteFamily
).
authentication(< AuthContext >ctx) - The client has requested authentication. ctx.username
contains the client username, ctx.method
contains the requested authentication method, and ctx.accept()
and ctx.reject([< Array >authMethodsLeft[, < Boolean >isPartialSuccess]])
are used to accept or reject the authentication request respectively. abort
is emitted if the client aborts the authentication request. Other properties/methods available on ctx
depends on the ctx.method
of authentication the client has requested:
hostbased
:
blob - Buffer - This contains the data to be verified that is passed to (along with the signature) key.verify()
where key
is a public key parsed with parseKey()
.
key - object - Contains information about the public key sent by the client:
algo - string - The name of the key algorithm (e.g. ssh-rsa
).
data - Buffer - The actual key data.
localHostname - string - The local hostname provided by the client.
localUsername - string - The local username provided by the client.
signature - Buffer - This contains a signature to be verified that is passed to (along with the blob) key.verify()
where key
is a public key parsed with parseKey()
.
keyboard-interactive
:
prompt(< array >prompts[, < string >title[, < string >instructions]], < function >callback) - (void) - Send prompts to the client. prompts
is an array of { prompt: 'Prompt text', echo: true }
objects (prompt
being the prompt text and echo
indicating whether the client's response to the prompt should be echoed to their display). callback
is called with (responses)
, where responses
is an array of string responses matching up to the prompts
.
submethods - array - A list of preferred authentication "sub-methods" sent by the client. This may be used to determine what (if any) prompts to send to the client.
password
:
password - string - This is the password sent by the client.
requestChange(< string >prompt, < function >callback) - (void) - Sends a password change request to the client. callback
is called with (newPassword)
, where newPassword
is the new password supplied by the client. You may accept, reject, or prompt for another password change after callback
is called.
publickey
:
blob - mixed - If the value is undefined
, the client is only checking the validity of the key
. If the value is a Buffer, then this contains the data to be verified that is passed to (along with the signature) key.verify()
where key
is a public key parsed with parseKey()
.
key - object - Contains information about the public key sent by the client:
algo - string - The name of the key algorithm (e.g. ssh-rsa
).
data - Buffer - The actual key data.
signature - mixed - If the value is undefined
, the client is only checking the validity of the key
. If the value is a Buffer, then this contains a signature to be verified that is passed to (along with the blob) key.verify()
where key
is a public key parsed with parseKey()
.
close() - The client socket was closed.
end() - The client socket disconnected.
error(< Error >err) - An error occurred.
handshake(< object >negotiated) - Emitted when a handshake has completed (either initial or rekey). negotiated
contains the negotiated details of the handshake and is of the form:
// In this particular case `mac` is empty because there is no separate MAC // because it's integrated into AES in GCM mode { kex: 'ecdh-sha2-nistp256', srvHostKey: 'rsa-sha2-512', cs: { // Client to server algorithms cipher: 'aes128-gcm', mac: '', compress: 'none', lang: '' }, sc: { // Server to client algorithms cipher: 'aes128-gcm', mac: '', compress: 'none', lang: '' } }
openssh.streamlocal(< function >accept, < function >reject, < object >info) - Emitted when the client has requested a connection to a UNIX domain socket. accept()
returns a new Channel instance representing the connection. info
contains:
ready() - Emitted when the client has been successfully authenticated.
rekey() - Emitted when a rekeying operation has completed (either client or server-initiated).
request(< mixed >accept, < mixed >reject, < string >name, < object >info) - Emitted when the client has sent a global request for name
(e.g. tcpip-forward
or cancel-tcpip-forward
). accept
and reject
are functions if the client requested a response. If bindPort === 0
, you should pass the chosen port to accept()
so that the client will know what port was bound. info
contains additional details about the request:
cancel-tcpip-forward
and tcpip-forward
:
bindAddr - string - The IP address to start/stop binding to.
bindPort - integer - The port to start/stop binding to.
cancel-streamlocal-forward@openssh.com
and streamlocal-forward@openssh.com
:
session(< function >accept, < function >reject) - Emitted when the client has requested a new session. Sessions are used to start interactive shells, execute commands, request X11 forwarding, etc. accept()
returns a new Session instance.
tcpip(< function >accept, < function >reject, < object >info) - Emitted when the client has requested an outbound (TCP) connection. accept()
returns a new Channel instance representing the connection. info
contains:
destIP - string - Destination IP address of outgoing connection.
destPort - string - Destination port of outgoing connection.
srcIP - string - Source IP address of outgoing connection.
srcPort - string - Source port of outgoing connection.
end() - (void) - Closes the client connection.
forwardOut(< string >boundAddr, < integer >boundPort, < string >remoteAddr, < integer >remotePort, < function >callback) - (void) - Alert the client of an incoming TCP connection on boundAddr
on port boundPort
from remoteAddr
on port remotePort
. callback
has 2 parameters: < Error >err, < Channel >stream.
openssh_forwardOutStreamLocal(< string >socketPath, < function >callback) - (void) - Alert the client of an incoming UNIX domain socket connection on socketPath
. callback
has 2 parameters: < Error >err, < Channel >stream.
rekey([< function >callback]) - (void) - Initiates a rekey with the client. If callback
is supplied, it is added as a one-time handler for the rekey
event.
x11(< string >originAddr, < integer >originPort, < function >callback) - (void) - Alert the client of an incoming X11 client connection from originAddr
on port originPort
. callback
has 2 parameters: < Error >err, < Channel >stream.
auth-agent(< mixed >accept, < mixed >reject) - The client has requested incoming ssh-agent requests be forwarded to them. accept
and reject
are functions if the client requested a response.
close() - The session was closed.
env(< mixed >accept, < mixed >reject, < object >info) - The client requested an environment variable to be set for this session. accept
and reject
are functions if the client requested a response. info
has these properties:
key - string - The environment variable's name.
value - string - The environment variable's value.
exec(< mixed >accept, < mixed >reject, < object >info) - The client has requested execution of a command string. accept
and reject
are functions if the client requested a response. accept()
returns a Channel for the command execution. info
has these properties:
pty(< mixed >accept, < mixed >reject, < object >info) - The client requested allocation of a pseudo-TTY for this session. accept
and reject
are functions if the client requested a response. info
has these properties:
cols - integer - The number of columns for the pseudo-TTY.
height - integer - The height of the pseudo-TTY in pixels.
modes - object - Contains the requested terminal modes of the pseudo-TTY keyed on the mode name with the value being the mode argument. (See the table at the end for valid names).
rows - integer - The number of rows for the pseudo-TTY.
width - integer - The width of the pseudo-TTY in pixels.
sftp(< mixed >accept, < mixed >reject) - The client has requested the SFTP subsystem. accept
and reject
are functions if the client requested a response. accept()
returns an SFTP instance in server mode (see the SFTP
documentation for details). info
has these properties:
shell(< mixed >accept, < mixed >reject) - The client has requested an interactive shell. accept
and reject
are functions if the client requested a response. accept()
returns a Channel for the interactive shell.
signal(< mixed >accept, < mixed >reject, < object >info) - The client has sent a signal. accept
and reject
are functions if the client requested a response. info
has these properties:
SIGUSR1
).subsystem(< mixed >accept, < mixed >reject, < object >info) - The client has requested an arbitrary subsystem. accept
and reject
are functions if the client requested a response. accept()
returns a Channel for the subsystem. info
has these properties:
window-change(< mixed >accept, < mixed >reject, < object >info) - The client reported a change in window dimensions during this session. accept
and reject
are functions if the client requested a response. info
has these properties:
cols - integer - The new number of columns for the client window.
height - integer - The new height of the client window in pixels.
rows - integer - The new number of rows for the client window.
width - integer - The new width of the client window in pixels.
x11(< mixed >accept, < mixed >reject, < object >info) - The client requested X11 forwarding. accept
and reject
are functions if the client requested a response. info
has these properties:
cookie - string - The X11 authentication cookie encoded in hexadecimal.
protocol - string - The name of the X11 authentication method used (e.g. MIT-MAGIC-COOKIE-1
).
screen - integer - The screen number to forward X11 connections for.
single - boolean - true
if only a single connection should be forwarded.
This is a normal streams2 Duplex Stream (used both by clients and servers), with the following changes:
A boolean property allowHalfOpen
exists and behaves similarly to the property of the same name for net.Socket
. When the stream's end() is called, if allowHalfOpen
is true
, only EOF will be sent (the server can still send data if they have not already sent EOF). The default value for this property is true
.
A close
event is emitted once the channel is completely closed on both the client and server.
Client-specific:
For exec():
An exit
event may (the SSH2 spec says it is optional) be emitted when the process finishes. If the process finished normally, the process's return value is passed to the exit
callback. If the process was interrupted by a signal, the following are passed to the exit
callback: null, < string >signalName, < boolean >didCoreDump, < string >description.
If there was an exit
event, the close
event will be passed the same arguments for convenience.
A stderr
property contains a Readable stream that represents output from stderr.
For exec() and shell():
The readable side represents stdout and the writable side represents stdin.
setWindow(< integer >rows, < integer >cols, < integer >height, < integer >width) - (void) - Lets the server know that the local terminal window has been resized. The meaning of these arguments are described in the 'Pseudo-TTY settings' section.
signal(< string >signalName) - (void) - Sends a POSIX signal to the current process on the server. Valid signal names are: 'ABRT', 'ALRM', 'FPE', 'HUP', 'ILL', 'INT', 'KILL', 'PIPE', 'QUIT', 'SEGV', 'TERM', 'USR1', and 'USR2'. Some server implementations may ignore this request if they do not support signals. Note: If you are trying to send SIGINT and you find signal()
doesn't work, try writing '\x03'
to the Channel stream instead.
Server-specific:
For exec-enabled channel instances there is an additional method available that may be called right before you close the channel. It has two different signatures:
exit(< integer >exitCode) - (void) - Sends an exit status code to the client.
exit(< string >signalName[, < boolean >coreDumped[, < string >errorMsg]]) - (void) - Sends an exit status code to the client.
For exec and shell-enabled channel instances, channel.stderr
is a writable stream.
cols - < integer > - Number of columns. Default: 80
height - < integer > - Height in pixels. Default: 480
modes - < object > - An object containing Terminal Modes as keys, with each value set to each mode argument. Default: null
rows - < integer > - Number of rows. Default: 24
term - < string > - The value to use for $TERM. Default: 'vt100'
width - < integer > - Width in pixels. Default: 640
rows
and cols
override width
and height
when rows
and cols
are non-zero.
Pixel dimensions refer to the drawable area of the window.
Zero dimension parameters are ignored.
Name | Description |
---|---|
CS7 | 7 bit mode. |
CS8 | 8 bit mode. |
ECHOCTL | Echo control characters as ^(Char). |
ECHO | Enable echoing. |
ECHOE | Visually erase chars. |
ECHOKE | Visual erase for line kill. |
ECHOK | Kill character discards current line. |
ECHONL | Echo NL even if ECHO is off. |
ICANON | Canonicalize input lines. |
ICRNL | Map CR to NL on input. |
IEXTEN | Enable extensions. |
IGNCR | Ignore CR on input. |
IGNPAR | The ignore parity flag. The parameter SHOULD be 0 if this flag is FALSE, and 1 if it is TRUE. |
IMAXBEL | Ring bell on input queue full. |
INLCR | Map NL into CR on input. |
INPCK | Enable checking of parity errors. |
ISIG | Enable signals INTR, QUIT, [D]SUSP. |
ISTRIP | Strip 8th bit off characters. |
IUCLC | Translate uppercase characters to lowercase. |
IXANY | Any char will restart after stop. |
IXOFF | Enable input flow control. |
IXON | Enable output flow control. |
NOFLSH | Don't flush after interrupt. |
OCRNL | Translate carriage return to newline (output). |
OLCUC | Convert lowercase to uppercase. |
ONLCR | Map NL to CR-NL. |
ONLRET | Newline performs a carriage return (output). |
ONOCR | Translate newline to carriage return-newline (output). |
OPOST | Enable output processing. |
PARENB | Parity enable. |
PARMRK | Mark parity and framing errors. |
PARODD | Odd parity, else even. |
PENDIN | Retype pending input. |
TOSTOP | Stop background jobs from output. |
TTY_OP_ISPEED | Specifies the input baud rate in bits per second. |
TTY_OP_OSPEED | Specifies the output baud rate in bits per second. |
VDISCARD | Toggles the flushing of terminal output. |
VDSUSP | Another suspend character. |
VEOF | End-of-file character (sends EOF from the terminal). |
VEOL2 | Additional end-of-line character. |
VEOL | End-of-line character in addition to carriage return and/or linefeed. |
VERASE | Erase the character to left of the cursor. |
VFLUSH | Character to flush output. |
VINTR | Interrupt character; 255 if none. Similarly for the other characters. Not all of these characters are supported on all systems. |
VKILL | Kill the current input line. |
VLNEXT | Enter the next character typed literally, even if it is a special character |
VQUIT | The quit character (sends SIGQUIT signal on POSIX systems). |
VREPRINT | Reprints the current input line. |
VSTART | Continues paused output (normally control-Q). |
VSTATUS | Prints system status line (load, command, pid, etc). |
VSTOP | Pauses output (normally control-S). |
VSUSP | Suspends the current program. |
VSWTCH | Switch to a different shell layer. |
VWERASE | Erases a word left of cursor. |
XCASE | Enable input and output of uppercase characters by preceding their lowercase equivalents with "". |
http.Agent
instance used to tunnel an HTTP connection over SSH. sshConfig
is what is passed to client.connect()
and agentOptions
is passed to the http.Agent
constructor.https.Agent
instance used to tunnel an HTTP connection over SSH. sshConfig
is what is passed to client.connect()
and agentOptions
is passed to the https.Agent
constructor.parseKey(< mixed >keyData[, < string >passphrase]) - mixed - Parses a private/public key in OpenSSH, RFC4716, or PPK format. For encrypted private keys, the key will be decrypted with the given passphrase
. keyData
can be a Buffer or string value containing the key contents. The returned value will be an array of objects (currently in the case of modern OpenSSH keys) or an object with these properties and methods:
comment - string - The comment for the key
equals(< mixed >otherKey) - boolean - This returns true
if otherKey
(a parsed or parseable key) is the same as this key. This method does not compare the keys' comments
getPrivatePEM() - string - This returns the PEM version of a private key
getPublicPEM() - string - This returns the PEM version of a public key (for either public key or derived from a private key)
getPublicSSH() - string - This returns the SSH version of a public key (for either public key or derived from a private key)
isPrivateKey() - boolean - This returns true
if the key is a private key or not
sign(< mixed >data) - mixed - This signs the given data
using this key and returns a Buffer containing the signature on success. On failure, an Error will be returned. data
can be anything accepted by node's sign.update()
.
type - string - The full key type (e.g. 'ssh-rsa'
)
verify(< mixed >data, < Buffer >signature) - mixed - This verifies a signature
of the given data
using this key and returns true
if the signature could be verified. On failure, either false
will be returned or an Error will be returned upon a more critical failure. data
can be anything accepted by node's verify.update()
.
sftp.OPEN_MODE - OPEN_MODE
sftp.STATUS_CODE - STATUS_CODE
sftp.flagsToString - flagsToString()
sftp.stringToFlags - stringToFlags()
identities(< opaque >request) - (Server mode only) The client has requested a list of public keys stored in the agent. Use failureReply()
or getIdentitiesReply()
to reply appropriately.
sign(< opaque >request, < mixed >pubKey, < Buffer >data, < object >options) - (Server mode only) The client has requested data
to be signed using the key identified by pubKey
. Use failureReply()
or signReply()
to reply appropriately. options
may contain any of:
'sha256'
or 'sha512'
for RSA keys.(constructor)(< boolean >isClient) - Creates and returns a new AgentProtocol instance. isClient
determines whether the instance operates in client or server mode.
failureReply(< opaque >request) - (void) - (Server mode only) Replies to the given request
with a failure response.
getIdentities(< function >callback) - (void) - (Client mode only) Requests a list of public keys from the agent. callback
is passed (err, keys)
where keys
is a possible array of public keys for authentication.
getIdentitiesReply(< opaque >request, < array >keys) - (void) - (Server mode only) Responds to a identities list request
with the given array of keys in keys
.
sign(< mixed >pubKey, < Buffer >data, < object >options, < function >callback) - (void) - (Client mode only) Requests that the agent sign data
using the key identified by pubKey
. pubKey
can be any parsed (using utils.parseKey()
) or parseable key value. callback
is passed (err, signature)
where signature
is a possible Buffer containing the signature for the data
. options
may contain any of:
'sha256'
or 'sha512'
for RSA keys.signReply(< opaque >request, < Buffer >signature) - (void) - (Server mode only) Responds to a sign request
with the given signature in signature
.
In order to create a custom agent, your class must:
Extend BaseAgent
Call super()
in its constructor
Implement at least the following methods:
getIdentities(< function >callback) - (void) - Passes (err, keys)
to callback
where keys
is a possible array of public keys for authentication.
sign(< mixed >pubKey, < Buffer >data, < object >options, < function >callback) - (void) - Signs data
using the key identified by pubKey
. pubKey
can be any parsed (using utils.parseKey()
) or parseable key value. callback
should be passed (err, signature)
where signature
is a possible Buffer containing the signature for the data
. options
may contain any of:
'sha256'
or 'sha512'
for RSA keys.Additionally your class may implement the following method in order to support agent forwarding on the client:
(err, stream)
to callback
where stream
is a possible Duplex stream to be used to communicate with your agent. You will probably want to utilize AgentProtocol
as agent forwarding is an OpenSSH feature, so the stream
needs to be able to transmit/receive OpenSSH agent protocol packets.Client
's agent
configuration option: if the platform is Windows and it's the value "pageant", it creates a PageantAgent
, otherwise if it's not a path to a Windows pipe it creates a CygwinAgent
. In all other cases, it creates an OpenSSHAgent
.socketPath
in a Cygwin environment.socketPath
.Author: mscdex
Source Code: https://github.com/mscdex/ssh2
License: MIT license
1654864800
manssh
manssh is a command line tool for managing your ssh alias config easily, inspired by storm project, powered by Go.
Note:
This project is actually a simple glue project, the most complex and core parsing ssh config file logic implements by ssh_config, I didn't do much.
At first it was just a imitation of storm, now it has become a little different.
Before 1.17
go get -u github.com/xwjdsh/manssh/cmd/manssh
1.17 or higher
go install github.com/xwjdsh/manssh/cmd/manssh
brew tap xwjdsh/tap
brew install xwjdsh/tap/manssh
alias manssh='docker run -t --rm -v ~/.ssh/config:/root/.ssh/config wendellsun/manssh'
Download it from releases, and extract it to your PATH
directory.
% manssh
NAME:
manssh - Manage your ssh alias configs easily
USAGE:
manssh [global options] command [command options] [arguments...]
VERSION:
master
COMMANDS:
add, a Add a new SSH alias record
list, l List or query SSH alias records
update, u Update SSH record by specifying alias name
delete, d Delete SSH records by specifying alias names
backup, b Backup SSH config files
help, h Shows a list of commands or help for one command
GLOBAL OPTIONS:
--file value, -f value (default: "/Users/wendell/.ssh/config")
--help, -h show help
--version, -v print the version
# manssh add test2 2.2.2.2
# manssh add test1 root@1.1.1.1:77 -c IdentityFile=~/.ssh/wendell
% manssh add test1 root@1.1.1.1:77 -i ~/.ssh/wendell
✔ alias[test1] added successfully.
test1 -> root@1.1.1.1:77
identityfile = /Users/wendell/.ssh/wendell
Username and port config is optional, the username is current login username and port is 22
by default.
Using -c
to set more config options. For convenience, -i xxx
can instead of -c identityfile=xxx
.
# manssh list
# manssh list "*"
# manssh list Test -ic
% manssh list test1 77
✔ Listing 1 records.
test1 -> root@1.1.1.1:77
identityfile = /Users/wendell/.ssh/wendell
It will display all alias records If no params offered, or it will using params as keywords query alias records.
If there is a -it
option, it will ignore case when searching.
# manssh update test1 -r test2
# manssh update test1 root@1.1.1.1:22022
% manssh update test1 -i "" -r test3 -c hostname=3.3.3.3 -c port=22022
✔ alias[test3] updated successfully.
test3 -> root@3.3.3.3:22022
Update an existing alias record, it will replace origin user, hostname, port config's if connected string param offered.
You can use -c
to update single and extra config option, -c identityfile= -c proxycommand=
will remove identityfile
and proxycommand
options.
For convenience, -i xxx
can instead of -c identityfile=xxx
Rename the alias specified by -r
flag.
# manssh delete test1
% manssh delete test1 test2
✔ alias[test1,test2] deleted successfully.
% manssh backup ./config_backup
✔ backup ssh config to [./config_backup] successfully.
If you use the Include
directive, there are some extra notes.
Add -p
(--path) flag for list
,add
,update
,delete
command to show the file path where the alias is located, it can also be set by the MANSSH_SHOW_PATH environment variable.
MANSSH_SHOW_PATH
Set to true
to show the file path where the alias is located. Default is false
.
Add -ap
(--addpath) flag for add
command to specify the file path to which the alias is added, it can also be set by the MANSSH_ADD_PATH environment variable.
MANSSH_ADD_PATH
This file path indicates to which file to add the alias. Default is the entry config file.
For convenience, you can export these environments in your .zshrc
or .bashrc
, example:
export MANSSH_SHOW_PATH=true
export MANSSH_ADD_PATH=~/.ssh/config.d/temp
Author: xwjdsh
Source Code: https://github.com/xwjdsh/manssh
License: MIT license
1654859640
GUIを備えていないRaspberryPiまたはその他のLinuxシステムでコードを作成する必要があったことはありますか?コピーアンドペーストのコマンドを覚えておくのは、vi
定期的に使用しない人にとってはほとんど不可能です。また、構文の強調表示、リンティング、さらには2つのファイルを並べて表示するなどの基本的なことも見逃します。
ありがたいことに、リモート/ヘッドレスシステムに接続するVS Codeの拡張機能があり、デスクトップでVS Codeを使用して、リモートファイルシステム上のファイルを編集できます。
Raspberry Piで実行することを目的としたコードを作成している場合は、PCではなくそのPiで開発作業を行うのが理にかなっています。土壇場で発見したくない言語とプラットフォームの依存関係があります。
多くのLinuxシステムにはグラフィカルコンソールがないため、そのリモートシステムで開発作業を行おうとすると、言語固有の拡張機能や素晴らしいグラフィカル統合などに慣れてきたVSCodeの機能が失われてしまいます。 gitとGitHub。
しかし、この難問を解決するVSCode拡張機能があります。
それはどのように見えますか?
SSH経由でリモートのVSCodeは、慣れているVS Codeであるため、慣れているVSCodeと同じように見えます。下のスクリーンショットでは、左側にあるおなじみのファイルツリーに注目してください。これらはリモートシステム上のファイルです!これらのファイルは、使い慣れたVS Codeコントロールを使用して、リモートシステムで開いたり、編集したり、保存したり、削除したりできます。
SSH拡張機能を備えたVSコード—作成者によるスクリーンショット
また、このスクリーンショットで開いているターミナルセッションがあることに注意してください。これは、リモートシステム上のターミナルセッションです。他のSSHウィンドウと同じように、このターミナルからコードをコンパイルして実行できます。
何が違うの?
SSH拡張機能をVSCodeにインストールすると、VSCodeウィンドウの左下隅に緑色のバーが表示されます。これをクリックすると、リモートホストに接続またはリモートホストから切断するためのメニューが表示されます。VS Codeは、必要に応じてお気に入りを追跡します。このスクリーンショットは、でLinuxホストに接続されているVSCodeウィンドウを示しています192.168.9.86
。
リモートホストに接続します—作成者によるスクリーンショット
リモートシステムに接続したら、[フォルダを開く]をクリックしてリモートシステム上の任意のディレクトリを開くことができます。また、最近の接続とリモートディレクトリのリストを提供する新しいアイコンがサイドバーにあることに注意してください。
リモートディレクトリを開く—作成者によるスクリーンショット
インストールして開始する
この拡張機能をインストールして開始するのは簡単です。VS Codeの「Extensions」に移動し、「SSH」を検索して、という名前のMicrosoft拡張機能で「Install」をクリックするだけRemote-SSH
です。それでおしまい!VSCodeを再起動する必要はありません。
拡張機能のインストール—作成者によるスクリーンショット
拡張機能がインストールされたら、VSCodeウィンドウの左下隅にある緑色のバーをクリックして接続を開始します。
接続するには緑色のバーをクリックします—作成者によるスクリーンショット
次に、下のスクリーンショットに示すように、手動で入力するuser@host
か、[新しいSSHホストの追加...]をクリックして、頻繁にアクセスするホストへのブックマークを作成できます。
ユーザー名とホスト名を指定します—作成者によるスクリーンショット
結論
私は学校で毎週RaspberryPiで小さなCプロジェクトに取り組んでいますが、このVS Code拡張機能をインストールしてから、使用したことはなく、一度もvi
使用していません。nano
私は言語拡張機能へのアクセス、gitとGitHubへの統合、そしてマウスを使用する贅沢さえも本当に大切にしています!
VS CodeのRemote-SSH
拡張機能は私にとって価値のあるツールであり、同様に価値があると感じていただければ幸いです。
このストーリーは、もともとhttps://betterprogramming.pub/learn-to-code-remotely-with-vs-code-and-ssh-68c630759279で公開されました
1654859418
¿Alguna vez ha tenido que escribir código en una Raspberry Pi u otro sistema Linux que no tenía una GUI? Tratar de recordar los comandos para copiar y pegar vi
es casi imposible para aquellos que no lo usan regularmente. También echas de menos cosas como el resaltado de sintaxis, la pelusa e incluso lo básico como mirar dos archivos uno al lado del otro.
Afortunadamente, ahora hay una extensión para VS Code que se conecta a sistemas remotos/sin periféricos, lo que le permite usar VS Code en su escritorio para editar archivos en el sistema de archivos remoto.
Si estoy escribiendo un código destinado a ejecutarse en una Raspberry Pi, entonces tiene sentido hacer el trabajo de desarrollo en esa Pi y no en mi PC. Hay dependencias de idioma y plataforma que no quiero descubrir en el último minuto.
Muchos sistemas Linux no tienen una consola gráfica, por lo que si trato de hacer ese trabajo de desarrollo en ese sistema remoto, termino perdiendo funciones en VS Code a las que me he acostumbrado, como extensiones específicas del idioma y una excelente integración gráfica con git y github.
Pero hay una extensión de VS Code que resuelve este enigma.
¿Cómo se ve?
El control remoto de VS Code a través de SSH se parece al VS Code al que está acostumbrado porque es el VS Code al que está acostumbrado. En la captura de pantalla a continuación, observe el árbol de archivos familiar a la izquierda. ¡Estos son los archivos en el sistema remoto! Puede abrir, editar, guardar o eliminar estos archivos en el sistema remoto con los mismos controles de VS Code con los que está familiarizado.
Código VS con extensión SSH: captura de pantalla del autor
Observe también que hay una sesión de terminal abierta en esta captura de pantalla. Esta es una sesión de terminal en el sistema remoto. ¡Puede compilar y ejecutar código desde este terminal como lo haría desde cualquier ventana SSH!
¿Que es diferente?
Después de instalar la extensión SSH en VS Code, verá una barra verde en la esquina inferior izquierda de la ventana de VS Code. Al hacer clic aquí, aparecerá un menú para conectarse o desconectarse de un host remoto. VS Code incluso hará un seguimiento de sus favoritos si lo desea. Esta captura de pantalla muestra mi ventana de VS Code conectada a un host Linux en 192.168.9.86
.
Conectarse al host remoto: captura de pantalla del autor
Una vez que se haya conectado a un sistema remoto, tendrá la oportunidad de hacer clic en "Abrir carpeta" para abrir cualquier directorio en el sistema remoto. Además, observe que hay un nuevo icono en la barra lateral que proporciona una lista de conexiones recientes y directorios remotos.
Abrir directorios remotos: captura de pantalla del autor
Instalar y comenzar
Es simple instalar esta extensión y comenzar. Simplemente vaya a "Extensiones" en VS Code, busque "SSH" y haga clic en "Instalar" en la extensión de Microsoft llamada Remote-SSH
. ¡Eso es todo! Ni siquiera tiene que reiniciar VS Code.
Instalación de la extensión: captura de pantalla del autor
Una vez que la extensión esté instalada, simplemente haga clic en la barra verde en la esquina inferior izquierda de su ventana de VS Code para iniciar una conexión.
Haga clic en la barra verde para conectarse: captura de pantalla del autor
Luego, puede ingresar manualmente user@host
o hacer clic en "Agregar nuevo host SSH ..." para crear un marcador para un host visitado con frecuencia como se muestra en la captura de pantalla a continuación.
Especifique el nombre de usuario y el nombre de host: captura de pantalla del autor
Conclusión
He estado trabajando en pequeños proyectos C en una Raspberry Pi todas las semanas para la escuela, pero no he usado vi
ni nano
una sola vez desde que instalé esta extensión de VS Code.
Realmente valoro el acceso a las extensiones de idioma, la integración con git y GitHub, ¡e incluso el lujo de usar un mouse!
La Remote-SSH
extensión para VS Code es una herramienta valiosa para mí y espero que la encuentre igualmente valiosa.
Esta historia se publicó originalmente en https://betterprogramming.pub/learn-to-code-remotely-with-vs-code-and-ssh-68c630759279