easyssh

README

easyssh-proxy

easyssh-proxy provides a simple implementation of some SSH protocol features in Go.

Feature

This project is forked from easyssh but add some features as the following.

• Support plain text of user private key.
• Support key path of user private key.
• Support Timeout for the TCP connection to establish.
• Support SSH ProxyCommand.

     +--------+       +----------+      +-----------+
     | Laptop | <-->  | Jumphost | <--> | FooServer |
     +--------+       +----------+      +-----------+

                         OR

     +--------+       +----------+      +-----------+
     | Laptop | <-->  | Firewall | <--> | FooServer |
     +--------+       +----------+      +-----------+
     192.168.1.5       121.1.2.3         10.10.29.68

Usage

You can see ssh, scp, ProxyCommand on examples folder.

ssh

See example/ssh/ssh.go

package main

import (
	"fmt"
	"time"

	"github.com/appleboy/easyssh-proxy"
)

func main() {
	// Create MakeConfig instance with remote username, server address and path to private key.
	ssh := &easyssh.MakeConfig{
		User:   "appleboy",
		Server: "example.com",
		// Optional key or Password without either we try to contact your agent SOCKET
		// Password: "password",
		// Paste your source content of private key
		// Key: `-----BEGIN RSA PRIVATE KEY-----
		// MIIEpAIBAAKCAQEA4e2D/qPN08pzTac+a8ZmlP1ziJOXk45CynMPtva0rtK/RB26
		// 7XC9wlRna4b3Ln8ew3q1ZcBjXwD4ppbTlmwAfQIaZTGJUgQbdsO9YA==
		// -----END RSA PRIVATE KEY-----
		// `,
		KeyPath: "/Users/username/.ssh/id_rsa",
		Port:    "22",
		Timeout: 60 * time.Second,

		// Parse PrivateKey With Passphrase
		Passphrase: "1234",

		// Optional fingerprint SHA256 verification
		// Get Fingerprint: ssh.FingerprintSHA256(key)
		// Fingerprint: "SHA256:mVPwvezndPv/ARoIadVY98vAC0g+P/5633yTC4d/wXE"

		// Enable the use of insecure ciphers and key exchange methods.
		// This enables the use of the the following insecure ciphers and key exchange methods:
		// - aes128-cbc
		// - aes192-cbc
		// - aes256-cbc
		// - 3des-cbc
		// - diffie-hellman-group-exchange-sha256
		// - diffie-hellman-group-exchange-sha1
		// Those algorithms are insecure and may allow plaintext data to be recovered by an attacker.
		// UseInsecureCipher: true,
	}

	// Call Run method with command you want to run on remote server.
	stdout, stderr, done, err := ssh.Run("ls -al", 60*time.Second)
	// Handle errors
	if err != nil {
		panic("Can't run remote command: " + err.Error())
	} else {
		fmt.Println("don is :", done, "stdout is :", stdout, ";   stderr is :", stderr)
	}
}

scp

See example/scp/scp.go

package main

import (
	"fmt"

	"github.com/appleboy/easyssh-proxy"
)

func main() {
	// Create MakeConfig instance with remote username, server address and path to private key.
	ssh := &easyssh.MakeConfig{
		User:     "appleboy",
		Server:   "example.com",
		Password: "123qwe",
		Port:     "22",
	}

	// Call Scp method with file you want to upload to remote server.
	// Please make sure the `tmp` floder exists.
	err := ssh.Scp("/root/source.csv", "/tmp/target.csv")

	// Handle errors
	if err != nil {
		panic("Can't run remote command: " + err.Error())
	} else {
		fmt.Println("success")
	}
}

SSH ProxyCommand

See example/proxy/proxy.go

	ssh := &easyssh.MakeConfig{
		User:    "drone-scp",
		Server:  "localhost",
		Port:    "22",
		KeyPath: "./tests/.ssh/id_rsa",
		Proxy: easyssh.DefaultConfig{
			User:    "drone-scp",
			Server:  "localhost",
			Port:    "22",
			KeyPath: "./tests/.ssh/id_rsa",
		},
	}

SSH Stream Log

See example/stream/stream.go

func main() {
	// Create MakeConfig instance with remote username, server address and path to private key.
	ssh := &easyssh.MakeConfig{
		Server:  "localhost",
		User:    "drone-scp",
		KeyPath: "./tests/.ssh/id_rsa",
		Port:    "22",
		Timeout: 60 * time.Second,
	}

	// Call Run method with command you want to run on remote server.
	stdoutChan, stderrChan, doneChan, errChan, err := ssh.Stream("for i in {1..5}; do echo ${i}; sleep 1; done; exit 2;", 60*time.Second)
	// Handle errors
	if err != nil {
		panic("Can't run remote command: " + err.Error())
	} else {
		// read from the output channel until the done signal is passed
		isTimeout := true
	loop:
		for {
			select {
			case isTimeout = <-doneChan:
				break loop
			case outline := <-stdoutChan:
				fmt.Println("out:", outline)
			case errline := <-stderrChan:
				fmt.Println("err:", errline)
			case err = <-errChan:
			}
		}

		// get exit code or command error.
		if err != nil {
			fmt.Println("err: " + err.Error())
		}

		// command time out
		if !isTimeout {
			fmt.Println("Error: command timeout")
		}
	}
}

Documentation

Overview

Package easyssh provides a simple implementation of some SSH protocol features in Go. You can simply run a command on a remote server or get a file even simpler than native console SSH client. You don't need to think about Dials, sessions, defers, or public keys... Let easyssh think about it!

Index

• type DefaultConfig
• type MakeConfig
  • func (ssh_conf *MakeConfig) Connect() (*ssh.Session, *ssh.Client, error)
  • func (ssh_conf *MakeConfig) Run(command string, timeout ...time.Duration) (outStr string, errStr string, isTimeout bool, err error)
  • func (ssh_conf *MakeConfig) Scp(sourceFile string, etargetFile string) error
  • func (ssh_conf *MakeConfig) Stream(command string, timeout ...time.Duration) (<-chan string, <-chan string, <-chan bool, <-chan error, error)

Types

type DefaultConfig

type DefaultConfig struct {
	User         string
	Server       string
	Key          string
	KeyPath      string
	Port         string
	Passphrase   string
	Password     string
	Timeout      time.Duration
	Ciphers      []string
	KeyExchanges []string
	Fingerprint  string

	// Enable the use of insecure ciphers and key exchange methods.
	// This enables the use of the the following insecure ciphers and key exchange methods:
	// - aes128-cbc
	// - aes192-cbc
	// - aes256-cbc
	// - 3des-cbc
	// - diffie-hellman-group-exchange-sha256
	// - diffie-hellman-group-exchange-sha1
	// Those algorithms are insecure and may allow plaintext data to be recovered by an attacker.
	UseInsecureCipher bool
}

DefaultConfig for ssh proxy config

type MakeConfig

type MakeConfig struct {
	User         string
	Server       string
	Key          string
	KeyPath      string
	Port         string
	Passphrase   string
	Password     string
	Timeout      time.Duration
	Proxy        DefaultConfig
	Ciphers      []string
	KeyExchanges []string
	Fingerprint  string

	// Enable the use of insecure ciphers and key exchange methods.
	// This enables the use of the the following insecure ciphers and key exchange methods:
	// - aes128-cbc
	// - aes192-cbc
	// - aes256-cbc
	// - 3des-cbc
	// - diffie-hellman-group-exchange-sha256
	// - diffie-hellman-group-exchange-sha1
	// Those algorithms are insecure and may allow plaintext data to be recovered by an attacker.
	UseInsecureCipher bool
}

MakeConfig Contains main authority information. User field should be a name of user on remote server (ex. john in ssh john@example.com). Server field should be a remote machine address (ex. example.com in ssh john@example.com) Key is a path to private key on your local machine. Port is SSH server port on remote machine. Note: easyssh looking for private key in user's home directory (ex. /home/john + Key). Then ensure your Key begins from '/' (ex. /.ssh/id_rsa)

func (*MakeConfig) Connect

func (ssh_conf *MakeConfig) Connect() (*ssh.Session, *ssh.Client, error)

Connect to remote server using MakeConfig struct and returns *ssh.Session

func (*MakeConfig) Run

func (ssh_conf *MakeConfig) Run(command string, timeout ...time.Duration) (outStr string, errStr string, isTimeout bool, err error)

Run command on remote machine and returns its stdout as a string

func (*MakeConfig) Scp

func (ssh_conf *MakeConfig) Scp(sourceFile string, etargetFile string) error

Scp uploads sourceFile to remote machine like native scp console app.

func (*MakeConfig) Stream

func (ssh_conf *MakeConfig) Stream(command string, timeout ...time.Duration) (<-chan string, <-chan string, <-chan bool, <-chan error, error)

Stream returns one channel that combines the stdout and stderr of the command as it is run on the remote machine, and another that sends true when the command is done. The sessions and channels will then be closed.