gsh

README

gsh

tectum.sh/gsh is yet another wrapper for the golang.org/x/crypto/ssh package. gsh is both a Go client API and a command line tool.

Since it understand OpenSSH's configuration files, it can be used as a drop-in replacement for ssh for simple use-case (it is not feature-complete yet).

Getting started with the command line tool

The quickest way to give the gsh a try is to use provided Docker images. Once the container is built and started, it will serve as OpenSSH server that the gsh can connect to.

In order to build and start the container, run the following commands:

./sshtest/build.sh

docker run --rm -d -ti -p 2222:22 -P sshtest-ubuntu:latest

Then build the gsh command line tool and connect to the container:

go build github.com/rjeczalik/gsh/cmd/gsh

gsh -F sshtest/ssh.config sshtest

To run a command as administrator (user "root"), use "sudo <command>".
See "man sudo_root" for details.

sshtest@9ddf71ccfd81:~$ 

Getting started with the client API

Equivalent code for the above gsh command looks like the following:

package main

import (
	"context"
	"log"

	"github.com/rjeczalik/gsh"
	"github.com/rjeczalik/gsh/sshfile"
	"github.com/rjeczalik/gsh/sshutil"
)

func main() {
	ctx := context.Background()

	cfg := &sshfile.Config{
		User:         "sshtest",
		Hostname:     "127.0.0.1",
		Port:         2222,
		IdentityFile: "sshtest/key.pem",
	}

	client := &gsh.Client{
		ConfigCallback: cfg.Callback(),
		DialContext:    sshutil.DialContext,
	}

	conn, err := client.Connect(ctx, "tcp", "")
	if err != nil {
		log.Fatal(err)
	}

	shell := gsh.Command("/bin/bash").Shell()

	if err := conn.Session(shell); err != nil {
		log.Fatal(err)
	}
}

Give it a try by running:

go run examples/sshtest.go

To run a command as administrator (user "root"), use "sudo <command>".
See "man sudo_root" for details.

sshtest@9ddf71ccfd81:~$ 

Documentation

Index

• Variables
• type Client
  • func (c *Client) Connect(ctx context.Context, network, address string) (Conn, error)
• type Cmd
  • func Command(cmd string, args ...string) *Cmd
  • func (c *Cmd) Do(ctx context.Context, s *ssh.Session) error
  • func (c *Cmd) Shell() *Shell
  • func (c *Cmd) String() string
• type Config
  • func (cfg *Config) Callback() ConfigCallback
  • func (cfg *Config) With(opts ...Option) *Config
  • func (cfg *Config) WithAuth(methods ...ssh.AuthMethod) *Config
• type ConfigCallback
• type Conn
• type DialContext
• type Heartbeat
• type Option
• type Retry
• type Session
• type SessionFunc
  • func (fn SessionFunc) Do(ctx context.Context, s *ssh.Session) error
• type Shell
  • func (sh *Shell) Do(ctx context.Context, s *ssh.Session) error

Variables

var (
	ConfigKey = contextKey{"ssh-config"}
	ConnKey   = contextKey{"ssh-conn"}
	ClientKey = contextKey{"ssh-client"}
)

var ErrConfigNotFound = errors.New("config not found")

Types

type Client

type Client struct {
	ConfigCallback
	DialContext
}

func (*Client) Connect

func (c *Client) Connect(ctx context.Context, network, address string) (Conn, error)

type Cmd

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

func Command

func Command(cmd string, args ...string) *Cmd

func (*Cmd) Do

func (c *Cmd) Do(ctx context.Context, s *ssh.Session) error

func (*Cmd) Shell

func (c *Cmd) Shell() *Shell

func (*Cmd) String

func (c *Cmd) String() string

type Config

type Config struct {
	ssh.ClientConfig `json:"-" yaml:"-"`

	Network     string
	Address     string
	KeepAlive   bool
	Connection  Retry
	ServerAlive Heartbeat
}

func (*Config) Callback

func (cfg *Config) Callback() ConfigCallback

func (*Config) With

func (cfg *Config) With(opts ...Option) *Config

func (*Config) WithAuth

func (cfg *Config) WithAuth(methods ...ssh.AuthMethod) *Config

type ConfigCallback

type ConfigCallback func(ctx context.Context, network, addr string) (*Config, error)

type Conn

type Conn interface {
	Session(Session) error
	Context() context.Context
	Close() error
}

type DialContext

type DialContext func(ctx context.Context, network, addr string) (net.Conn, error)

type Heartbeat

type Heartbeat struct {
	Interval time.Duration
	MaxCount int
}

type Option

type Option interface {
	Apply(*Config) *Config
}

type Retry

type Retry struct {
	Timeout  time.Duration
	MaxCount int
}

type Session

type Session interface {
	Do(context.Context, *ssh.Session) error
}

type SessionFunc

type SessionFunc func(context.Context, *ssh.Session) error

func (SessionFunc) Do

func (fn SessionFunc) Do(ctx context.Context, s *ssh.Session) error

type Shell

type Shell struct {
	*Cmd
}

func (*Shell) Do

func (sh *Shell) Do(ctx context.Context, s *ssh.Session) error