xerox

README

SSH tunneling and SSH client implemented in Golang..

What is Xerox?

Xerox assassin is a Golang library which helps you to make connection to a remove machine, using SSH client or SSH tunnel.

Install package

Import package by using the following command:

go get -v github.com/amirhnajafiz/xerox@latest

Check to see if the package is installed:

import (
    _ "github.com/amirhnajafiz/xerox"
)

Using Xerox to create SSH tunnel

// creating the local, server, and remote servers
localEndpoint := &xerox.Endpoint{
    Host: "localhost",
    Port: 9000,
}
serverEndpoint := &xerox.Endpoint{
    Host: "example.com",
    Port: 22,
}
remoteEndpoint := &xerox.Endpoint{
    Host: "localhost",
    Port: 8080,
}
// creating ssh client config
sshConfig := &ssh.ClientConfig{
    User: "vcap",
    Auth: []ssh.AuthMethod{
        xerox.SSHAgent(os.Getenv("SSH_AUTH")),
    },
}
// creating xerox ssh tunnel
sshTunnel := &xerox.SSHTunnel{
    Local:  localEndpoint,
    Server: serverEndpoint,
    Remote: remoteEndpoint,
    Config: sshConfig,
}

log.Printf("ssh tunnel start...")

// starting ssh tunnel
if err := sshTunnel.Start(); err != nil {
    panic(err)
}

Using Xerox to create SSH Client

// creating ssh config
sshConfig := &ssh.ClientConfig{
    User: "root",
    Auth: []ssh.AuthMethod{
        xerox.PublicKeyFile("./.private-key"),
    },
}

// creating ssh client
client := &xerox.SSHClient{
    Config: sshConfig,
    Server: &xerox.Endpoint{
        Host: "129.0.4.22",
        Port: 80,
    },
    TerminalConfig: &xerox.SSHTerminal{
        Echo:             0,
        TtyOpInputSpeed:  14400,
        TtyOpOutputSpeed: 14400,
        Rows:             80,
        Columns:          40,
    },
}

// connecting to remove machine
if err := client.Connect(); err != nil {
    panic(err)
}

Executing commands:

// generating our command
cmd := &xerox.SSHCommand{
    Path:   "ls -l $LC_DIR",
    Env:    []string{"LC_DIR=/usr"},
    Stdin:  os.Stdin,
    Stdout: os.Stdout,
    Stderr: os.Stderr,
}

// running command
if err := client.RunCommand(cmd); err != nil {
    panic(err)
}

Documentation

Index

• func PublicKeyFile(file string) ssh.AuthMethod
• func SSHAgent(sshAuth string) ssh.AuthMethod
• type Endpoint
  • func (endpoint *Endpoint) String() string
• type SSHClient
  • func (client *SSHClient) Connect() error
  • func (client *SSHClient) RunCommand(cmd *SSHCommand) error
• type SSHCommand
• type SSHTerminal
• type SSHTunnel
  • func (tunnel *SSHTunnel) Start() error

Functions

func PublicKeyFile

func PublicKeyFile(file string) ssh.AuthMethod

PublicKeyFile If you want to authenticate by using SSH certificate you need to create a public key file. You can parse your private key file by using ssh.ParsePrivateKey function. This is required by ssh.PublicKeys auth method function that creates ssh.AuthMethod instance from private key.

func SSHAgent

func SSHAgent(sshAuth string) ssh.AuthMethod

SSHAgent is a program that runs during user session in *nix system. It stores the private keys in an encrypted form. Because typing the passphrase can be tedious, many users would prefer to use it to store their private keys. You can obtain all stored keys via sshAuth variable which stores the SSH agent unix socket. We should access the keys by calling net.Dial and then instance an agent client used by ssh.PublicKeysCallback factory auth method.

Types

type Endpoint

type Endpoint struct {
	// server host address
	Host string
	// server port
	Port int
}

Endpoint The tunneling protocol allows a network user to access or provide a network service that the underlying network does not support or provide directly. There are three type of server: - remote server - local server - target server each server can be represented by the following struct.

func (*Endpoint) String

func (endpoint *Endpoint) String() string

returns the string of our endpoint.

type SSHClient

type SSHClient struct {
	Server         *Endpoint
	Config         *ssh.ClientConfig
	TerminalConfig *SSHTerminal
	// contains filtered or unexported fields
}

SSHClient using SSH client to run a shell command on a remote machine. Every SSH connection requires an ssh.ClientConfig object that defines configuration options such as authentication. Session is one of the parameters that acts as an entry point to the remote terminal.

func (*SSHClient) Connect

func (client *SSHClient) Connect() error

Connect opening a new connection to remote machine and creating a new session.

func (*SSHClient) RunCommand

func (client *SSHClient) RunCommand(cmd *SSHCommand) error

RunCommand executes commands.

type SSHCommand

type SSHCommand struct {
	Path   string
	Env    []string
	Stdin  io.Reader
	Stdout io.Writer
	Stderr io.Writer
}

SSHCommand is used for sending and receiving commands to our remote machine.

type SSHTerminal

type SSHTerminal struct {
	Echo             uint32
	TtyOpInputSpeed  uint32
	TtyOpOutputSpeed uint32
	Columns          int
	Rows             int
}

SSHTerminal to run the command on the remote machine, we should create a pseudo terminal on the remote machine. A pseudo-terminal (or “pty”) is a pair of virtual character devices that provide a bidirectional communication channel.

type SSHTunnel

type SSHTunnel struct {
	Local  *Endpoint
	Server *Endpoint
	Remote *Endpoint

	Config *ssh.ClientConfig
}

SSHTunnel The client is connecting to local endpoint. Then the server endpoint mediates between local endpoint and remote endpoint. The algorithm is encapsulated in SSHTunnel struct.

func (*SSHTunnel) Start

func (tunnel *SSHTunnel) Start() error

Start creating servers on SSHTunnel.