Skip to content

A haxelib that provides a basic SSH client which uses a pre-installed OpenSSH, Putty, or Kitty client under the hood.

License

Notifications You must be signed in to change notification settings

vegardit/haxe-sshclient

Repository files navigation

haxe-sshclient

Build Status Release License Contributor Covenant

  1. What is it?
  2. Installation
  3. Using the SSH client
  4. Using the latest code
  5. License

What is it?

A haxelib that provides a basic SSH client to execute commands on remote system. It uses a pre-installed OpenSSH, Putty, or Kitty client under the hood.

All classes are located in the package hx.sshclient or below.

Requirements/Limitations

  • Haxe Version: 4.2.0 or higher
  • Supported Targets: C++, C#, Neko, HashLink, Java/JVM, Python
  • Supported Operating Systems: Linux, MacOS, Windows
  • Preinstalled software: one of the following SSH clients must be installed:
    • Linux/MacOS: OpenSSH (ssh), Putty (plink)
    • Windows: OpenSSH (ssh.exe), Putty (plink.exe), Kitty (klink.exe)
  • Password-based authentication is only supported when using Putty/Kitty.

Installation

  1. MacOS, Linux and Windows 10 or higher have OpenSSH client preinstalled. If you want to use password based authentication install Putty or Kitty client:

  2. Install the library via haxelib using the command:

    haxelib install haxe-sshclient
    
  3. Use the library in your Haxe project:

    • for OpenFL/Lime projects add <haxelib name="haxe-sshclient" /> to your project.xml
    • for free-style projects add -lib haxe-sshclient to your *.hxml file or as command line option when running the Haxe compiler

Using the SSH client

Configuring a Putty/Kitty based SSH client

The following code creates an SSH client backed by Putty/Kitty with default settings that:

  • either uses Putty or Kitty depending on which client was found on the system path - or fails if neither is found
  • uses HostKeyChecking strategy Strict, i.e. only connects to hosts that are already known
  • connects to port 22
import hx.sshclient.PuttySSHClient;
//...
var sshClient = PuttySSHClient.builder()
   .withHostname("myhost")
   .withUsername("myuser")
   .withSecret(Password("mypassword"))
   .build();

The SSH client can be further configured:

import hx.sshclient.PuttySSHClient;
//...
var sshClient = PuttySSHClient.builder()
   .withHostname("myhost")
   .withPort(2222) // use a different port
   .withUsername("myuser")
   .withSecret(IdentityFile("C:\\Users\\myser\\mykey.ppk")) // use a private key for autentication
   .withHostKeyChecking(AcceptNew) // allow connection to new hosts but prevent connections to known hosts with mismatching host keys
   .withExecutable("C:\\apps\\network\\putty\\plink.exe") // specify the client binary to be used
   .build();

Configuring an OpenSSH based SSH client

The following code creates an SSH client backed by OpenSSH with default settings that:

  • either uses an OpenSSH client or fails if not found on the system path
  • uses HostKeyChecking strategy Strict, i.e. only connects to hosts that are already known
  • connects to port 22
import hx.sshclient.OpenSSHClient;
//...
var sshClient = OpenSSHClient.builder()
   .withHostname("myhost")
   .withUsername("myuser")
   .withSecret(IdentityFile("/home/myuser/ssh/id_rsa")) // use a private key for authentication
   .build();

The SSH client can be further configured:

import hx.sshclient.OpenSSHClient;
//...
var sshClient = PuttySSHClient.builder()
   .withHostname("myhost")
   .withPort(2222) // use a different port
   .withUsername("myuser")
   .withHostKeyChecking(AcceptNew) // allow connection to new hosts but prevent connections to known hosts with mismatching host keys
   .withExecutable("/opt/openssh/bin/ssh") // specify the client binary to be used
   .build();

Executing a remote command via SSH

Once you have created an ssh client object you can execute remote commands:

var cmd = sshClient.execute("whoami");
cmd.awaitSuccess(5000); // wait 5 seconds for a successful response, throws an exception otherwise
var output = cmd.stdout.readAll().trim(); // retrieve the output of the executed command
trace('result: ${output}');

Using the latest code

Using haxelib git

haxelib git haxe-sshclient https://github.com/vegardit/haxe-sshclient main D:\haxe-projects\haxe-sshclient

Using Git

  1. check-out the main branch

    git clone https://github.com/vegardit/haxe-sshclient --branch main --single-branch D:\haxe-projects\haxe-sshclient
  2. register the development release with Haxe

    haxelib dev haxe-sshclient D:\haxe-projects\haxe-sshclient

License

All files are released under the Apache License 2.0.

Individual files contain the following tag instead of the full license text:

SPDX-License-Identifier: Apache-2.0

About

A haxelib that provides a basic SSH client which uses a pre-installed OpenSSH, Putty, or Kitty client under the hood.

Topics

Resources

License

Code of conduct

Stars

Watchers

Forks

Packages

No packages published