proxyssh

package module
v0.2.2 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jun 1, 2022 License: MIT Imports: 13 Imported by: 0

README

proxyssh

CI Status

A golang package based on https://github.com/gliderlabs/ssh that enables easily creating different ssh servers. Also includes Docker support.

Use Cases

The main use case of this package is to provide a simple interface to build an ssh server that runs commands on the host it is running on. See the cmd/simplesshd package.

A secondary use case is to provide an ssh server that runs commands in matching docker containers. See the cmd/dockersshd package.

A third use case of this package is to provide an ssh server that provides no shell access, but permits port forwarding only. See the cmd/exposshed package.

For a more detailed overall documentation, see the godoc.

Tests

This package comes with a tests suite as well as a builtin memory-leak detector. The tests can be run as any normal go test suite can:

go test ./...

Some tests place requirement on the test machine. Concretely, these require:

  • a running docker installation

  • a working docker-compose command

  • a /bin/bash executable These special tests are not run by default, but only when the dockertests tag is provided. Use something like:

    go test -tags=dockertest ./...

to run them. The memory leak detector is not enabled by default and not used during the tests. By default, all code calling the memory leak detector is removed during compilation.

The detector can be enabled by adding the leak go build tag. When enabled, all executables output memory leak messages for every connection to the console.

Dockerfiles

This repository contains Dockerfiles for all of the examples, called cmd/${example}/Dockerfile.

These are available as the GitHub Packages dockersshd, simplesshd and exposshed respectively.

The dockersshd image can be run as follows:

docker run --rm -v /var/run/docker.sock:/var/run/docker.sock -p 2222:2222 ghcr.io/tkw1536/dockersshd:latest

To e.g. allow clients to expose port 8080 the exposshed image can be run as follows

docker run -t -v /path/to/hostkeys:/data/ -i --rm -p 2222:localhost:2222 -p 8080:8080 ghcr.io/tkw1536/exposshed:latest -R 0.0.0.0:8080

Documentation

Overview

Package proxyssh provides facilities to create an ssh server that executes commands on the local machine.

This package is very much a wrapper around github.com/gliderlabs/ssh. However it additionally provides convenient functions to build a local server that behaves much like an OpenSSH server.

Index

Constants

This section is empty.

Variables

View Source 
var ErrHandlerAlreadySet = errors.New("ApplyHandler: Handler already set")

ErrHandlerAlreadySet is returned by ApplyHandler when a handler is already applies to the server.

Functions

func ApplyConfiguration added in v0.2.0 

func ApplyConfiguration(logger logging.Logger, server *ssh.Server, configuration Configuration) error

ApplyConfiguration applies a configuration to the provided ssh.Server.

To apply a configuration, first the configuration.Apply() function is called. When Configuration implements Handler, additionally calls ApplyHandler().

When a configuration is nil, ApplyConfiguration does nothing.

func ApplyHandler added in v0.2.0 

func ApplyHandler(logger logging.Logger, server *ssh.Server, handler Handler) error

ApplyHandler applies a handler to a server by setting server.Handler. When server.Handler is already set, returns an error.

func NewServer added in v0.2.0 

func NewServer(logger logging.Logger, options *Options, configurations ...Configuration) (*ssh.Server, error)

NewServer makes a new server, applies the appropriate configurations, and then applies the options.

Types

type Configuration added in v0.2.0 

type Configuration interface {
	Apply(logger logging.Logger, server *ssh.Server) error
}

Configuration is a configuration for an ssh.Server.

type Handler added in v0.2.0 

type Handler interface {
	Handle(logger logging.Logger, session ssh.Session) (Process, error)
}

Handler represents a Configuration that provides a handler.

type Options 

type Options struct {
	// ListenAddress is the address to listen on.
	// It should be of the form 'address:port'.
	ListenAddress string

	// HostKeyPath is the path to which the host keys are stored.
	// HostKeyAlgorithms are the algorithms to use for host keys.
	//
	// When HostKeyPath is not the empty string, will pass both to UseOrMakeHostKeys.
	HostKeyPath       string
	HostKeyAlgorithms []feature.HostKeyAlgorithm

	// DisableAuthentication allows to completly skip the authentication.
	// This will result in a warning printed to the server
	DisableAuthentication bool

	// ForwardAddresses are addresses that port forwarding is allowed for.
	// ReverseAddresses are addresses that reverse port forwarding is allowed for.
	//
	// See the AllowPortForwarding method for details.
	ForwardAddresses []feature.NetworkAddress
	ReverseAddresses []feature.NetworkAddress

	// IdleTimeout is the timeout after which a connection is considered idle.
	IdleTimeout time.Duration
}

Options are options that implement features shared by several server implementations.

func (*Options) Apply added in v0.2.0 

func (opts *Options) Apply(logger logging.Logger, sshserver *ssh.Server) error

Apply applies the common options to server.

func (*Options) RegisterFlags added in v0.2.0 

func (opts *Options) RegisterFlags(flagset *flag.FlagSet, addUnsafeFlags bool)

RegisterFlags registers flags representing the options to the provided flagset. When flagset is nil, uses flag.CommandLine.

addUnsafeFlags indiciates if unsafe flags should be added as well.

type Process added in v0.2.0 

type Process interface {
	fmt.Stringer

	// Init initializes this process
	Init(ctx context.Context, detector logging.MemoryLeakDetector, isPty bool) error
	Start(detector logging.MemoryLeakDetector, Term string, resizeChan <-chan WindowSize, isPty bool) (*os.File, error)

	// Input / Output Streams
	Stdout() (io.ReadCloser, error)
	Stderr() (io.ReadCloser, error)
	Stdin() (io.WriteCloser, error)

	// Wait waits for the process and returns the exit code
	Wait(detector logging.MemoryLeakDetector) (int, error)

	// Cleanup is called to cleanup this process, usually to kill it.
	Cleanup() (killed bool)
}

Process represents a runnable object with input and output streams.

type Session added in v0.2.0 

type Session struct {
	ssh.Session                // the underlying ssh.session
	Logger      logging.Logger // for logging

	Process Process // the process that this session should execute
	// contains filtered or unexported fields
}

Session represents an ongoing ssh.Session executing a Process

func (*Session) Run added in v0.2.0 

func (c *Session) Run() error

Run runs this session and waits for it to complete. After a call to this function ssh.Session will have closed.

If this session was already started, immediatly returns an error. If something goes wrong when starting the session also returns an error.

type WindowSize added in v0.2.0 

type WindowSize = term.Size

WindowSize represents the size of the window

Source Files

View all Source files

Directories

Path Synopsis
cmd
dockersshd
Command dockersshd provides an ssh server that executes commands inside docker.
 Command dockersshd provides an ssh server that executes commands inside docker.
exposshed
Command exposshed provides an daemon that allows clients to use local and remote port forwarding.
 Command exposshed provides an daemon that allows clients to use local and remote port forwarding.
simplesshd
Command simplesshd provides a simple ssh daemon that works similar to OpenSSH.
 Command simplesshd provides a simple ssh daemon that works similar to OpenSSH.
config
dockerexec
Package dockerexec provides ContainerExecConfig.
 Package dockerexec provides ContainerExecConfig.
osexec
Package osexec provides SystemExecConfig.
 Package osexec provides SystemExecConfig.
terminal
Package terminal provides REPLConfig.
 Package terminal provides REPLConfig.
Package feature provides several re-usable features for ssh servers.
 Package feature provides several re-usable features for ssh servers.
Package internal contains code only for use within proxyssh.
 Package internal contains code only for use within proxyssh.
asyncio
Package asyncio provides context-aware alternatives to io methods.
 Package asyncio provides context-aware alternatives to io methods.
integrationtest
Package integrationtest provides shared code for integrationtests.
 Package integrationtest provides shared code for integrationtests.
legal
Package legal contains legal notices of packages used by proxyssh.
 Package legal contains legal notices of packages used by proxyssh.
lock
Package lock provides various locking utilities.
 Package lock provides various locking utilities.
term
testutils
Package testutils contains functions used as utility code for tests.
 Package testutils contains functions used as utility code for tests.
Package logging provides Logger.
 Package logging provides Logger.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.